Donate

MiSTer is fully open source project and will remain open. This is my hobby and i'm getting fun to make hardware and software for this project. While software part just requires time, hardware requires money as well. To release a working add-on i have to make some test samples. Sometimes disaster happens and some equipment/device dies during experiments. Some bought devices/components intended to be MiSTer companions turned to be useless. So i have to try many options before give advice to users.

I'm not a big fan of asking donation for hobby projects, but this project sometimes requires investment to develop. It's absolutely voluntary, you don't have to. But if you satisfied my work and would be glad to donate, then here is my Paypal:

FAQ

This page contains commonly asked questions and their answers.

Table of Contents

When will MiSTer support cartridges?

MiSTer will never use physical cartridges.

Not only is it outside the scope of the project which aims to replace the need for having real hardware, it is physically very impractical/impossible given the number of GPIO pins available from the FPGA.

Does MiSTer have lag?

Short answer: No, not with a normal setup.

Long answer: You may see some latency depending on your display, controller and settings. But they can all be tweaked to a large extent if that is important to you. In general, if you use a CRT and native peripherals like an original console, you will experience no additional latency compared to it. See here for a more detailed explanation.

Any USB controller recommendations?

Please refer to this page

Can I use native controllers?

Short answer: Yes.

Long answer: Native controllers can be used with a USB adapter. There are a few specialized controllers that may not work as a regular gamepad (eg. Zapper), and for those it is possible to use a serial interface board (e.g. IO Board + SNAC). Native protocols via SNAC are currently supported for NES, SNES, and Genesis cores. Through this, a Zapper can be used with a CRT.

Does MiSTer need an IO board?

Short answer: No.

Long answer: The IO board is optional, but offers some features that might be important to some users. Being an Input/Output (IO) device, it’s primary function is to provide a native (like original hardware) video and audio signal to analog displays (CRTs) with zero lag (see FAQ 2 above) and audio devices via 3.5mm audio cable or optical (TOSLINK) output. Please note, HDMI video and audio will continue to function when using analog output. This dual output is especially useful for those who wish to capture/stream gameplay footage. The input side of the device refers to the serial port, which has the same physical appearance as a USB 3.0 port. It is not however, a true USB port, and does not support regular USB devices at all. See FAQ 4 above for more information on how you would use this part of the IO board. There are other small features of the IO board that serve minor purposes; please see this page for more information about them.

Do I need a Hub Add-On Board?

Short answer: No.

Long answer: The USB Hub Addon Board can be considered a luxury item. An inexpensive OTG USB HUB from online markets will work fine for many people. The advantage of the addon board is that it physically integrates very cleanly and safely with the DE10 and it has seven powered USB ports which is plenty for almost any user. Users who want to use many or several power hungry USB devices will want to at least be sure to get a USB Hub that is externally powered so as not to overtax the DE10’s power circuitry. Take care to pay attention to the DE10’s rather delicate OTG USB port. Another advantage of the addon board is that it very securely attaches to this port. Corded OTG Hub users will want to be careful that this port is not stressed by a sudden jerk or a slow steady pull.

Does my MiSTer need cooling?

Short answer: Yes, at least a heatsink (passive cooling).

Long answer: While it's fine for general operations, the DE-10 board’s FPGA chip ideally requires a passive heatsink to avoid heat interfering with some of the more complex cores. 22mm x 22mm is the ideal heatsink size for this. Active cooling (a fan) is recommended for long term use. Some cores may present corruption/artifacts if the chip is not cooled with a fan. A 40mm diameter fan, powered from either the IO board or directly from one of the DE-10’s GPIO pins, is the recommended type for this task. Typically this fan is mounted on the optional IO board, however it can also be mounted on a 3D-printed plate or hand-cut piece of plastic or cardboard if you do not need or have an IO board.

Do I need an IO board to get analog video output to my CRT?

Short answer: No. You can use an HDMI to VGA adapter to do it.

Long answer: Use of an inexpensive HDMI to VGA adapter is supported in most cores through Direct Video. These dongles can easily be found in online markets by searching.

I heard the DE10-Nano board uses subsidized components. Is MiSTer doomed if that stops?

The DE10 Nano is broadly sold to universities and is available in larger supply than custom hardware made only for retro enthusiasts. In general, these development boards are manufactured and sold for a long time (the last generation DE1 board is still sold), so there is no reason to be concerned. Worst case, the work done in cores can be ported to other boards in the future. For now, the DE10-Nano remains the best and most cost-effective option, and MiSTer is a perfect fit for it as the boards are intended to introduce FPGA programming to a wider audience.

What power supply is compatible with MiSTer / DE-10 Nano?

The DE10 boards needs a 5V power supply with at least 2A. One such PSU is included with the DE10-Nano board. The connector is a coaxial "barrel" plug of 5.5 mm outer diameter and 2.1 mm inner diameter, center positive.

Videos

This page aims to centralize good tutorials and introduction videos.

MiSTer FPGA Overview

MiSTer is an evolving platform, so these videos can only represent what was available at the time:

Tutorials

FPGA Discussion

(mentioning MiSTer)

Other / Demonstrations

What you will need

Requirements

In order to get started with the MiSTer platform, there are a few things that will be required. Optional addons are also available but for the bare minimum setup, you will need the following items :-

  • DE10-Nano Board with supplied power supply and SD card. (required)
  • USB OTG connector or OTG USB hub(required)
  • USB Keyboard (required)
  • HDMI Monitor & HDMI Cable (required)
  • Cooling (recommended)
  • Network Connection (recommended for initial setup and updates)
  • Micro SD card reader (required for initial setup)

1. DE10-Nano board

The heart and engine of the whole platform is the Terasic DE10-Nano development board, made in Taiwan.

You can buy it:

Or from major electronics suppliers such as:

A power supply unit (PSU) and 8GB MicroSD card is included with the kit. The SD card can be reformatted to use with your MiSTer. Any MicroSD card 2GB and larger should work fine as well. Speed class doesn't affect it.

2. USB connection

Most unpowered basic USB hubs will work. Although it is recommended that you use a powered USB OTG hub with your DE10-Nano board as it is not able to handle high current consumption, so depending on the peripherals you use, you may need an external powered hub.

If you're not connecting too many USB peripherals, it does handle a keyboard, mouse, and gamepad just fine. Do note that the USB socket isn't very robust so it is best to avoid connecting and disconnecting too often.

USB option 1:

Micro USB OTG cable + basic USB 2.0 hub.

A basic USB 2.0 hub, or one with external power would be a good idea both to eliminate OTG socket reliability issues and provide power to external devices. Some cheap ones on eBay/Aliexpress may be declared as full speed USB 2.0 but in fact work in USB low speed mode. They may be acceptable for keyboard, but better to avoid them.

USB option 2:

USB OTG Hub.

These hubs are designed to connect directly to the micro-USB OTG port and require less inter-connection cables. Such hubs are also available on eBay/Aliexpress.

USB option 3:

USB hub daughter board.

You can assemble or purchase this board that provides 7 USB ports available to the MiSTer system.

3. Cooling

The hybrid ARM+FPGA chip has been found to get hot even when idling in the core menu, therefore some passive cooling is recommended. The main heat producer in the chip is the integrated dual-core ARM processor producing a constant heat regardless of the FPGA core in use.

The Cyclone V FPGA chip on the DE10-Nano board is industrial grade and supports up to 100°C, but for guaranteed long term usage without degrading its characteristics, it's highly advisable to add at least a heatsink.

This chip is approximately 21.5mm x 21.5mm. Ideal dimensions of a heatsink is 22mm x 22mm, and it will cover all the FPGA. Commonly found heatsinks with dimensions ranging from 20mm x 20mm to 25mm x 25mm can be used, but for larger heatsinks pay attention to nearby components, they must not touch the heatsink.

The height of the heatsink should be no more than 10mm if an I/O board is used because it could touch parts in the I/O board and create short circuits.

Active cooling

Some large cores such as ao486 and Minimig are sensitive to FPGA chip temperature and become unstable if it becomes too hot. So active cooling, in addition to passive cooling, is recommended for stability.

If you're building or purchasing an I/O board, they are designed for a 40mm x 40mm fan. Assembled I/O boards should already have a fan installed.

If you do not use any I/O boards then you are free to choose any fan, but bear in mind that you should only use the 5V line from the Terasic DE10-Nano board to drive a 5V fan. (The DE10-Nano's 9V line is deliberately hidden by the MiSTer I/O board to prevent any possibility of accidentally shorting it to any other signals.) You may also consider a larger 12V fan, they should work but spin slower and still provide good airflow. (Do note that popular Noctua fans may not spin up when undervolted).

A large selection of fans can be found on most electronic components sites, such as Digikey, Mouser and many others.

Setup Guide

MiSTer Setup Guide

This is an essential guide for your first time setup of the MiSTer system. It will guide you through the SD card installation, help you update the MiSTer system files, and shows you how to install an example console core and run a game.

There are two option for getting started, the recommended method is to use the Mr Fusion setup script. This is the best option for beginners and works on all platforms.

The second option is a manual install which is only recommended for users with specific use cases.

Mr Fusion Installation Method (Recommended)

Mr Fusion provides a compact image that you can download and flash onto an SD card of any size with a tool like Apple Pi Baker, balenaEtcher, Win32 Disk Imager or even dd.

When you put this SD card into your DE10-nano and start it up, it will expand the card to its full capacity and install a basic MiSTer setup. This will be familiar to anyone who's worked with a Raspberry Pi before.

From there, using the built-in scripts, you can configure WiFi (or use ethernet out of the box) and run the standard MiSTer Updater script to get an up to date MiSTer installation.

Requirements

  • A Micro SD card of minimum 2 GB, for example the one that came with your DE10-nano kit.
  • Windows, Mac or Linux based computer with a (micro)SD card reader.
  • An SD card flash utility.

Instructions

Step 1

Download the latest version from the releases page.

Step 2

Download and install an SD card flash utility for your system. Here are a few example in no particular order:

Refer to the documentation of the SD card flash utility for more information.

Step 3

Follow your SD card flash utility's instructions to flash the downloaded image onto your SD card.

Note: Extract the downloaded SD card image zip file if your SD card flash utility does not support flashing zip files!

Step 4

Put the SD card into the DE10-nano and power it on. After a few seconds the orange LED on the board should light up. If you have a TV or monitor connected to the HDMI port, the screen will turn blue and then show an installation notice splash screen:

MiSTer installation splash screen

Mr. Fusion will automatically re-partition and resize your SD card and copy all the necessary MiSTer files onto it. When it's done it will reboot your DE10-nano and you will be greeted by the MiSTer menu.

Connect a keyboard to your DE10-nano and hit F12 to open the menu. Through the Scripts section you can configure WiFi and update your MiSTer.

Note: From powering on the DE10-nano and getting to the MiSTer menu should not take more than 90 seconds. If you don't see the MiSTer menu appear after two minutes, power off the DE10-nano, remove the SD card and start over.

MiSTer scripts support

The MiSTer updater script is included by default in every MiSTer installation. This image also includes the WiFi setup script to allow you to quickly setup a wireless internet connection after installation.

Adding more scripts

You can add more scripts if necessary: After you have flashed your SD card and before you move it over to the DE10-nano, re-insert it into your computer. A new drive called MRFUSION will appear. In it is a Scripts folder. Put any script you want to have available in your MiSTer in this folder. It will be copied to your MiSTer's Scripts folder automatically during the installation.

Manual Installation Method

Requirements

You will need the following things to get everything started.

For the SD card setup:

  • Windows 10 (recommended, older versions may work). For SD card creation under macOS and Linux, see this script.
  • Internet connection.
  • SD card reader.
  • SD card with at least 2GB capacity.

And to run it:

  • DE10-Nano board + 5V power supply (supplied with the board).
  • HDMI monitor + HDMI cable.
  • USB-OTG (Micro USB) adapter + USB keyboard.
  • SDRAM Board (Optional, but is required for a majority of the cores, see wiki page for instructions.)

Do check the How to start and Input devices wiki pages for further information.

Prepare the SD Card

  1. Download the latest SD card installer.

  2. Insert your SD card into your card reader. All data on the SD card will be deleted! Make sure that the correct drive is selected, and if needed, backup the SD card.

  3. Extract the release_201#####.rar file.

  4. Start MiSTer SD Card Utility.exe

  5. Make sure it says "Boot + Files" in the "Image" field.

    • Older versions of Mister SD card Utility (as pictured above) will say U-Boot + Linux + MiSTer in the Image field.
  6. Select your SD card in the Drive field. If you have inserted the SD card after starting the Installer, hit the Refresh button and your SD card should appear.

  7. The Installer may open multiple windows which will ask you to format the drive. If this happens, don't format the drive! Press Cancel in all windows.

  8. Press Full Install and confirm the following Warning with Yes. All data on the SD card will be deleted! If needed, make sure to backup the SD card before you execute this.

  9. Confirm the successful installation with OK

  10. The SD card file explorer window may be opened twice, if so, close one of them. The SD-card should contain the following files and folders:

    If you see only the menu.rbf file, hit F5 on your keyboard or right click > Refresh to refresh the window. You should see all of them now. There may be other files and folders, but these are the essentials.

    The files and folders you should see are:

    • linux - Folder containing linux files
    • config - The configuration folder where various config files are placed automatically. Those files usually don't need any manual modifications.
    • This folder is no more created by newer version of SD Card Utility, but it will be created automatically by the MiSTer hardware at first run (you can manually create and populate it if you want)
    • menu.rbf - This is the actual MiSTer menu core, which you will see when you boot up the DE10-Nano board (GitHub).
    • MiSTer - MiSTer main firmware (GitHub)

Update MiSTer files

The SD card installer will be older then the actual binary releases of the MiSTer firmware and the menu core. Therefore, we want to bring those files up to date.

  1. Go to the MiSTer-devel/Main_MiSTer Repository and download the most recent MiSTer_202##### firmware file on the bottom of the page.

  2. Rename the MiSTer_202##### file to MiSTer

  3. Copy the file over to your SD-card and override the old MiSTer file.

  4. Repeat this for the menu core file. Go to the MiSTer-devel/Menu_MiSTer repository and download the most recent menu_202#####.rbf core file on the bottom of the page. Rename menu_202#####.rbf to menu.rbf and override the old file on the SD card.

Get a core

We want to actually run a core like the NES or Genesis (Megadrive) console or Amiga computer on our DE10-Nano FPGA board. Therefore, we have to copy a core .rbf file to the root of the SD-card. The sidebar on the right contains a list of MiSTer compatible cores. Check out the GitHub repository page of each core for specific information.

The following description is a generic example based on the NES core, but it is applicable to most other cores.

Do note that the NES core requires additional SDRAM. If you do not have this add-on, you can still continue following the example by using the Genesis core (which does not require additional SDRAM) instead of NES.

  1. Click in the sidebar on Cores > "NES" or go directly through this link to the MiSTer-devel/NES_MiSTer release folder. Download the lates NES_20######.rbf core file

  2. Copy the core file to the root of the SD Card. Leave the date in the filename. By this, you know which version you are actually using.

  3. Create a new folder and name it for example NES Games.

  4. Download a .nes ROM (Game) file and copy it into your NES Games folder. You have to google that by yourself...

Fire it up!

  1. If you're using additional SDRAM, make sure the SDRAM-Board is properly attached to the GPIO header JP1 of the DE10-Nano board.

Connect the DE10-Nano board via HDMI to a monitor and via USB-OTG adapter to a keyboard. Do not connect the power supply as yet.

  1. Remove the SD card from your PC and insert it in the DE10-Nano board.

  2. Connect the power supply. This will turn on the DE10-Nano board. You will see the MiSTer menu on the monitor. You see in the menu the NES (or Genesis) core we have copied to the SD Card. Hit the Enter key to start it.

  3. You will see a black screen. This is normal because no ROM is loaded yet. Press F12 to bring up the MiSTer menu. In order to run a game, select "Load *.NES" and hit Enter.

  4. This will bring up the SD card root directory. Navigate into your "NES Games" folder and select the ROM you want to start and hit Enter.

  5. Congratulations, you have successfully started your first game on your new MiSTer!

Following steps

To get the most out of your MiSTer don't forget to (at least) check out the following pages:

Additional notes

Once you've installed Release_20180115 or later, you can install future updates on MiSTer without removing the SD card. It's done in 2 stages: 1) Copy everything from files folder of release to /media/fat using FTP client and then reboot MiSTer (use Left Shift + Left CTRL + Left Alt + Right Alt combination). 2) Log in via serial console or ssh and type updateboot then reboot again.

Usually the bootloader has little or no change and does not always require updating. But for a better experience it's advised to update the bootloader with every release. If by any chance a new version of Linux isn't able to boot with a previous bootloader, then simply use the SD card Installer Tool to update the bootloader (Update Boot button).

You may organize the cores into directories (folders) rather than have them stored on the root directory, to make these directories visible simply add an underscore in front of the directory name.

INI file

MiSTer.ini

The MiSTer.ini configuration file contains settings for the MiSTer.

A default copy of the file itself can be found here: MiSTer.ini

Download and copy the MiSTer.ini file to the root of your SD-Card. Open it with your favorite editor (e.g. Notepad++) and change the parameters accordingly to the following description.


List of INI Settings

Addtional Information


bootcore

If specified, selects core to run at startup (instead of menu) bootcore=lastcore Automatically loads the last used core bootcore=lastcoreexact Automatically loads the last used core, matching time stamp e.g. core_yyymmdd.rbf bootcore=[corename] Loads [corename]_*.rbf at startup (first file found on SD card) bootcore=[corename_yyyymmdd.rbf] Loads [corename_yyyymmdd].rbf at startup (exact file name)

You can still select Reboot in the system menu to get back to the main menu core.

bootcore_timeout

Number of seconds to wait before auto core boot. You can comment out this line by putting ; at the beginning to boot directly into the core with no timeout.

bootcore=10 Value can be 10 to 30 seconds

composite_sync

Use composite sync as horizontal sync signal on VGA output.

composite_sync=1 activate composite sync

composite_sync=0 deactivate composite sync

direct_video

Feature for using the HDMI port with DACs to produce analog video. See this page for more information.

direct_video=1 to activate it (disables compatibility with HDMI TVs and monitors).

direct_video=0 to deactivate it.

controller_info

Seconds to display controller settings when starting a new core.

Cores support automated mapping from central joystick mapping if no core-specific joystick mapping was defined. When this is active, MiSTer shows a tiny popup displaying the button assignment. This setting controls the time that pop-up is displayed (and can switch it off)

controller_info=0 Do not display mapping info pop-up

controller_info=1, controller_info=10 Seconds to display controller mapping pop up

forced_scandoubler

Run scandoubler on VGA output always (depends on core).

Most modern monitors won't support the 15 KHz horizontal sync output signal through the VGA connector. This option doubles the frequency of horizontal sync signal and brings it in a compatible range for modern monitors. Note that this is not a global option and is only valid for the MiSTer Menu. Each core drives the VGA output itself and requires its own setting. Check the core menu of the corresponding core via HDMI to set the scandoubler option if available / necessary.

forced_scandoubler=1 activate scandoubler

forced_scandoubler=0 deactivate scandoubler

hdmi_audio_96k

HDMI audio output options

hdmi_audio_96k=1 96khz/16bit HDMI audio

hdmi_audio_96k=0 48khz/16bit HDMI audio

hdmi_limited

Change between Full Range RGB and Limited Range RGB

hdmi_limited=0 Full Range RGB (0-255)

hdmi_limited=1 Limited Range RGB (16-235)

hdmi_limited=2 Limited Range common DAC variant (16-255)

jammasd_vid, jammasd_pid

USB vendor ID and product ID for JammaSD adapter, required for keypress-to-joystick translation.

Allows a JammaSD joystick to be read as a standard joystick rather than being read as a keyboard.

jammasd_vid Vendor ID

jammasd_pid Product ID

key_menu_as_rgui

Makes the MENU key map to RGUI in Minimig (e.g. for Right Amiga)

key_menu_as_rgui=1 set the MENU key map to RGUI

key_menu_as_rgui=0 dont set the MENU key map to RGUI

osd_rotate

Display OSD menu rotated.

osd_rotate=0 no rotation

osd_rotate=1 rotate right (+90°)

osd_rotate=2 rotate left (-90°)

recents

Set to 1 to enable showing recently played games. Once enabled, you can highlight or select the "Load file" option in a core menu and press the select button on your controller to show a list of recently loaded files. In the core selection menu, pressing select will show the recently loaded cores. Files and cores that have been moved or renamed since they were last loaded will appear faded out in the recents list.

(Note: using this mode increases writes to SD card, which may increase wear over the long term.)

recents=0 Default behavior - don't show recent files

recents=1 Show recent files

vga_scaler

This option makes the VGA (DB15) connector output of the scaler. In other words, it makes the VGA have the same resolution as HDMI (1080p or 720p, or as per your overall video settings).

vga_scaler=1 VGA DB15 connector will have the full scaler output

vga_scaler=0 VGA DB15 will have an independent video output, separate from main scaler (e.g. 240p or 480p)

video_info

Seconds to display video information on startup. Defaults to zero.

video_info=0 Do not display video info video_info=1, video_info=10 Specify number of seconds to show video info

vscale_mode

Options for integer scaling.

vscale_mode=0 scale to fit the screen height.

vscale_mode=1 use integer scale only.

vscale_mode=2 use 0.5 steps of scale.

vscale_mode=3 use 0.25 steps of scale.

vsync_adjust

Sets the vsync buffer mode for HDMI output. This setting does not affect direct video or analog output from the IO board.

Some HDMI displays can accept somewhat non-standard signals, allowing for lower display latency with MiSTer. It is recommended that you start with a setting of 0, and then try modes 1 and 2 to see if they work with your display or capture device.

vsync_adjust=0 Default. Buffered 60hz HDMI video output, compatible with most HDMI devices.

vsync_adjust=1 Adjust output HDMI Vsync to match original Vsync. Lower latency than mode 0, but less compatible.

vsync_adjust=2 Low-latency mode, using the system's native pixel clock. This mode has the lowest latency, but it's the least-compatible.

ypbpr

Use YPbPr signal on VGA output.

ypbpr=1 activate YPbPr

ypbpr=0 deactivate YPbPr

Adding Core-specific Settings

It is possible to specify different settings for different cores; for example, you may prefer to use integer scaling just for the Game Boy Advance core so that you don't need any video filters for smooth scrolling. Simply add a section at the end of the INI file with the core name in brackets and paste your different settings below there, like so:

[GBA]
vscale_mode=1

Menu core can have its own settings too. Section should be named [Menu]

Switching INI Files On the Fly

MiSTer currently supports up to 3 additional INI files that can be toggled in the OSD menu, either by going to Misc. Options (press left while in the menu) or by holding the menu back button on your controller and pressing a direction. This is useful if you need to switch between video configurations often. To get started, make copies of your INI file and rename them:

mister_alt_1.ini activated by back + left

mister_alt_2.ini activated by back + up

mister_alt_3.ini activated by back + down

Additionally, you can switch back to your default mister.ini by pressing back + right or by selecting Main.

Your alt INI file will stay loaded across reboots and core changes until you turn the power off; mister.ini will always load by default when powering on. Note that if you switch INI files while a core is running, the core will reset.

Using MiSTer

Using MiSTer

So, you've got your MiSTer, followed the "Setup Guide", now what?
Let's get you more familiar with what you can do!


Important MiSTer Menu Keys

F12 - brings up the Menu in a Core.

ALT F12 - brings up the Core Menu

F1 - changes the background

F11 - Bluetooth pairing menu (for supported BT adapters)

F9 - Linux prompt (Press F12 to switch back to the MiSTer menu as necessary)

Left Shift + Left Ctrl + Left Alt + Right Alt - Reboot

Windows + Print Screen - Screenshot


You'll need a USB keyboard, and internet for the MiSTer

Make sure both are plugged in, and power on the MiSTer. The red, orange and green led lights should start pulsing, and you should see the MiSTer menu onscreen after a second or two.

Staying Updated by using the update.sh script

We'll need to download the "update.sh" script from GitHub, so lets login to Linux and do so.
Press F9 to bring up the Linux prompt.
(Login with user "root", and password "1", then copy / paste the below)

cd /media/fat/Scripts

wget --no-check-certificate https://raw.githubusercontent.com/MiSTer-devel/Updater_script_MiSTer/master/update.sh -O update.sh

exit

That will download the updater for you in the correct folder. Once that's downloaded, it should exit back to the prompt, and we can now update the system from within MiSTer.
We only need to download that script once. Once its installed, you can simply run the updater from the Scripts menu.

Tip - Press F12 to bring up the System Menu (if you press F12 again, it will show the core menu).
Use the up and down arrow keys and enter to navigate the menu.

Fixing missing certs

The default system comes with no cert files, which is a bit annoying, as you need to add --no-check-certificate on wget to download anything HTTPS. Lets fix that.

ssh into your mister.

cd /etc/ssl/certs

wget --no-check-certificate https://curl.haxx.se/ca/cacert.pem

Assuming it downloaded correctly, you can now use wget as nature intended!

Updating our system

Open up the System Menu (F12)
Navigate to Scripts, then run "update" (use the cursor to move and press enter to select).
It will download all the latest cores for you and keep your MiSTer updated.
MiSTer cores are regularly updated - sometimes daily, so run "update" regularly!
Ok, you're updated, now what?


Samba Sharing Setup

Lets setup samba sharing. By default the samba script is disabled, so we need to rename it.
From your MiSTer -

Press F9 to go to the Linux prompt.
(The default user is "root", and the default password is "1")
Type or paste the following to enable samba, this will enable samba, and reboot MiSTer

cd /media/fat/linux

mv _samba.sh samba.sh

/media/fat/Scripts/samba_on.sh

reboot

If you press F12 again once rebooted, you can see the IP address of your MiSTer in the setup menu.
You can now navigate to your mister via \\IP ADDRESS on windows or smb://IP ADDRESS on Mac.
Check your IP address, and navigate to it.

eg if your IP address is 192.168.0.210

Windows

File, Run

\\192.168.0.210

to open the share.

Mac

Press APPLE K (cmd K)

smb://192.168.0.210

Click connect


You'll want to start copying appropriate file backups of your cartridges - i.e. roms to the appropriate locations.
I usually stick my Console or Computer roms in a folder called roms under the root folder, then sort by name under there.

eg;

/roms/Megadrive/... /roms/SNES/... /roms/NES/... etc

Arcade roms, Computer BIOS and Core system roms will need to be put elsewhere in a folder called bootrom.

/bootrom/ [ BIOS / Arcade Roms / Core roms go here ]


Important Folders or files - what goes where!

Note - If the folders or files don't exist make them!

If you are connecting over SSH or over Linux (F9) on the MiSTer then use the full folder name '/media/fat/...'

If connecting over SMB, then remove the /media/fat/ below as you are already in that folder! eg /media/fat/menu.jpg would simply be a file called menu.jpg in the root folder

/media/fat/menu.jpg or /media/fat/menu.png

Background menu image for MiSTer (Press F1 to cycle through when in the MiSTer menu). Needs to be a jpg or a png format file. MiSTer will resize it for you.

/media/fat/fonts

Fonts folder. Get your fonts here

Edit /media/fat/MiSTer.ini and edit font=fonts/xxx.pf to your choice of font

/media/fat/screenshots

Screenshots taken with Windows Key + PrintScreen will go in here

/media/fat/bootrom

Place your rom files in this folder. Cores will look in this folder first. Note that Arcade cores need to be built specially for MiSTer and copied in here. Instructions to build roms are in the core menu per core.

eg Asteroids, you will need to acquire the rom's from, uh, your PCB, and download the files from here - then run the build_rom.sh or bat file to create the MiSTer compatible file - a.asteroid.rom and finally copy that into to /media/fat/bootrom.

Core Status

Core Status

Cores on MiSTer are the result of the collaboration between many people and extensive testing, sometimes over many years and prior open-source projects. Most console and computer cores have now been compared to original hardware to a high level of precision (e.g. audio capture comparison), with the few issues remaining documented on their respective github repository pages. Please refer to these pages, per core, before submitting any issues.

The core links on the sidebar will bring you to the release folder on github, which will also allow you to find the Issues page and the readme files, listing all available features and limitations in detail per core.

Why FPGA?

A typical potential user will eventually ask, "Why do you need to use FPGA while other proven solutions exist, such as Raspberry Pi?"

There are debates about how to refer to the process of simulating real hardware using FPGA. Some people insist it's not emulation but rather true hardware replication, while any simulation using a traditional CPU should be referred to as emulation. I have my own opinion here. :) From my point of view, if the FPGA code is based on the circuitry of real hardware (along with the usual tweaks for FPGA compatibility), then it should be called replication. Anything else is emulation, since it uses different kinds of approximation to meet the same objectives. Currently, it's hard to find a core that can truly be called a replica – most cores are based on more-or-less functional recreations rather than true circuit recreation. The most widely used CPU cores – the Z80 (T80) and MC68000 (TG68K) – are pure functional emulations, not replications. So it's okay to call FPGA cores emulators, unless they are proven to be replicas.

To go back to the original question, then, why FPGA, if it's also just emulation? Well, FPGA emulation is fundamentally different than emulation on a CPU. Traditional emulators on CPUs execute code sequentially. This is a tricky method of emulation because real hardware has many chips and all of them work in parallel. The CPU, video chip/logic, audio chip, memory arbiter – all of them are working at the same time. So a traditional emulator has to take care of all these parts and try to emulate the whole orchestra at the same time by quickly "running" from one chip to another. This requires a lot of CPU power to emulate even an old and slow retro computer. Sometimes even a modern CPU working at 100 times the speed of the retro computer is not enough, so the emulator has to use approximation, skip emulation of some less important parts, or assume some standard work of the emulated system without extraordinary usage. Let's take a well-known emulator, UAE, emulating an Amiga. On a Raspberry Pi 3, you can run some Amiga CPU benchmarks and get crazy numbers like 100 times the original 68000 processor. So you may assume you have an emulated Amiga that is 100 times faster than real one. No, you don't. If you run different kinds of demos or games, you will see the video stutters sometimes. For example, if you play the well-known "State of The Art" demo by Spaceballs, you will notice video stuttering at some points, while a real Amiga 600 with 1x CPU speed plays the whole demo very smoothly. This is how traditional emulators on Raspberry Pi work.

FPGA emulation works very differently from traditional emulation on CPU. An FPGA is a large array of simple triggers and other logic – just like any other chip/CPU. The only difference is that specific chips/CPUs have these triggers and logic permanently connected, while FPGA allows you to connect them however you want. A special HDL (hardware description language) describes how to connect all these triggers/logic cells. Everything in FPGA works in parallel like in the original chips/devices. Thus, FPGA is pretty close to the original hardware. FPGA doesn't need high frequencies to emulate retro computers; it works at much lower frequencies than traditional emulators require. Since everything in FPGA works in parallel, it is no problem to handle any possible usage of the emulated system. Developers using FPGA usually concentrate on the specific part to make it work correctly – and it will work as it should in any possible scenario. In the same reference demo, "State Of the Art," using FPGA emulation, you can see smooth video through the whole playback, as on the original hardware.

You may want to ask, "So why not make all emulators on FPGA then?" The answer: FPGA programming is not so trivial. Every bit in FPGA works in parallel, so the developer needs to think in parallel as well :). What is trivial on CPU is not trivial on FPGA – although some parts that are trivial on FPGA cost a lot in CPU code.

What about Lag?

A common concern among retro enthusiasts is whether a device of this sort has lag and whether it will create a less desirable experience compared to original hardware.

Every electronic equipment exhibits some kind of latency, but it only becomes problematic if this latency causes frames to be missed. A frame is typically 16ms for a system using a 60 frames per second (60 Hz) display.

Lag is only problematic in a few specific cases:

  • Some older games were designed to rely on extremely quick response times (e.g. Punch-Out on NES).
  • If the latency is different between two players, it could introduce an unfair advantage.
  • Lag that isn't constant can be an issue on games that require precise movement. (Most players can adapt to lag that is consistent.)

There are three major categories of lag. Input, which involves controllers, mouse, etc, Processing, which would involve buffering in the core, execution or delays in code and Display which involves the output of the video to your display device.

For a more detailed overview of lag and exploration of it, please refer to this page: https://inputlag.science/

Input

For input, MiSTer primarily uses USB. In this case the overall input lag is the sum of the lag caused by the USB polling and the lag caused by the controller itself, how quickly it processes the signals. The latter is outside the scope of MiSTer and can only be improved by using a better controller. On the MiSTer side only the lag caused by the USB polling can be reduced if the connected USB device supports a lower polling interval. The polling interval is measured in Hz and indicates how often a USB device is polled per second. At 1000 Hz, a USB device is polled 1000 times per second, which means the additional lag caused by the polling is 1 s / 1000 = 1 ms in the worst case and 0.5 ms on average. This is a great improvement compared to the default value of 125 Hz, where a USB device is polled 125 times per second, which means the additional lag caused by the polling is 1 s / 125 = 8 ms in the worst case and 4 ms on average.

If a game is rendered at 60 frames per second, a single frame takes 1 s / 60 ≈ 16 ms to process. One might think that any polling interval below 16 ms would be perfect; however, USB polling happens independently of the vertical sync. Therefore, even with a 1 ms polling interval, there is a chance of 1/16 that the whole frame will be missed and input will be processed on the next frame. The longer the polling interval, the greater the odds of a missed frame. With a polling interval of 8 ms, the odds of input missing a frame are 50%. Native polling rates and input response vary across consoles and even games.

Processing

This is one core advantage of emulation using FPGAs. Unlike software emulators which go through a cycle of executing, and then waiting for a screen refresh, FPGA cores run in real time, as the original hardware did. This means that cores don’t have CPU bottlenecks to slow them down arbitrarily or require additional large buffers to hold data under most circumstances.

Display

MiSTer’s two primary display outputs are analog and HDMI.

The analog output is driven as the original system would have, with no buffering, and so it will be effectively identical to the latency of a real console. From this point of view, the analog output cannot have any form of lag.

When using HDMI output the image must be scaled up to fit the higher resolutions, which requires additional processing. The MiSTer scaler has options which impact its latency. Using vsync_adjust=2 in the ini file will result in about 4 scanlines of latency, while 0 or 1 will result in up to roughly 2 frames of latency, with the added advantage of being more compatible with displays.

In addition your own television or monitor may introduce more latency, but this varies by device and no definite number can be given on that here.

In summary, if lag is critical to you, it's best to play on a CRT using a recommended and widely-tested USB controller. Some users have tested and ranked USB controllers by performance; you can see their results here.

Do keep in mind, however, that even over HDMI MiSTer is capable of providing a better experience than many other devices.

Reducing Lag

Video lag

MiSTer offers options in how to configure its HDMI upscaler, making a tradeoff between compatibility and low latency. These can be set in the MiSTER.INI file at the root of the SD card:

  • vsync_adjust=2 is the best option if it is compatible with your TV. This mode uses the original refresh rate and pixel clock of the core, resulting in no additional latency.
  • vsync_adjust=1 is the second best option, but it adds up to 2 frames of latency. This mode uses a framebuffer but maintains the system's original vsync and varies the pixel clock per core.
  • vsync_adjust=0 is the lesser option, but the most compatible. Up to 2 frames of latency and less smooth scrolling. This mode guarantees 60 hz output with an NTSC standard pixel clock.

Input lag

USB controllers usually have an interval value which the host (MiSTer Linux kernel) respects to poll their inputs at. Most USB devices can actually perform better by being polled more often without any side effects.

To set a higher USB polling rate, you need to go to the "linux" subdirectory on your SD card and rename "u-boot.txt_example" to "u-boot.txt". The aforementioned file contains the following options, which should only be changed if you are encountering problems:

v=loglevel=4 usbhid.jspoll=1 xpad.cpoll=1

loglevel: 4 is the default value. You can set this to 9 to get debugging messages with dmesg command via SSH. If you just want to know which values of usbhid.jspoll and xpad.cpoll are applied to your controller, there are easier ways to achieve this (see below).

usbhid.jspoll: specifies the interval for USB HID controllers, usually DirectInput.

  • 0 is the default value MiSTer uses (even when there is no "u_boot.txt"). In this case the requested value from the controller is used.
  • 1 is the recommended value (which means 1000/1 = 1000 Hz polling rate). However, if you ever encounter any issues, try higher integer values. The higher the interval, the higher the possible lag. This shouldn't go above 8 (which means 1000/8 = 125 Hz polling rate).
  • To see which value is applied to your controller, you can run systool -m usbhid -A jspoll from the Linux shell.

xpad.cpoll: specifies the interval for USB XInput controllers. Most popular controllers use this. There is no practical difference here. XInput is for Microsoft's Xbox consoles and PC.

  • 0 is the default value MiSTer uses (even when there is no "u_boot.txt"). In this case the requested value from the controller is used.
  • 1 is the recommended value (which means 1000/1 = 1000 Hz polling rate). However, if you ever encounter any issues, try higher integer values. The higher the interval, the higher the possible lag. This shouldn't go above 8 (which means 1000/8 = 125 Hz polling rate).
  • To see which value is applied to your controller, you can run systool -m xpad -A cpoll from the Linux shell.

Input devices

MiSTer supports many different USB input devices.

Any USB HID compatible device will be recognized.

For recommendations you can refer to Selecting Input Devices.

Keyboard

A keyboard can emulate other input devices, so basically it is enough to control all cores.

MiSTer keyboard features a flexible key re-mapping function, mouse and gamepad emulation, and more.

See Keyboard for details

Mouse

MiSTer supports up to 3 buttons (exact number of mouse buttons is core-dependent).

Most USB wired and wireless mice, trackballs and touchpads will work.

Joystick and gamepads

MiSTer has a powerful set of features for USB gaming controllers:

Joystick player assignment

Up to 6 player controllers are supported (depending on core):

  • After a core starts, press a button on any connected controller to make it the P1 gamepad/joystick
  • Press a button on a second controller to make it the P2 joystick (if supported by core)
  • Keep going for assigning P3, P4, etc.
  • To remap, just clear all assignments by restarting the core.

USB Joystick mapping

USB joysticks, gamepads, and keyboards need to be defined in the central menu before use in any core. Please refer to Main Joystick Mapping

Auto fire

Any defined button (except d-pad) supports auto fire feature. To activate auto fire, press and keep desired button and then quickly press the button defined as "BUTTON OSD"(for joystick) or "KBD TOGGLE"(for keyboard). To deactivate auto fire, repeat the the same procedure.

Auto fire provides 50ms-1000ms rates. To choose the speed, press and keep one of direction on d-pad and then quickly press the button defined as "BUTTON OSD"(for joystick) or "KBD TOGGLE"(for keyboard).

Mouse emulation

Joystick can emulate mouse if required button "Mouse Emu" has been defined in default joystick definition (Menu core). Hold "Mouse Emu" button and "Alt/M", Mouse Left/Right/Middle Btn will emulate the mouse functions. Also defined analog stick for mouse will be switched to pointer functions. Press "BUTTON OSD" while holding "Mouse Emu" to toggle mouse emulation permanently. In permanent mouse emulation "Mouse Emu" button becomes a sniper button (smaller pointer movements). Only buttons defined for mouse emulation will be switched. Other joystick buttons will continue to act as joystick buttons. Thus, if your game pad has many buttons, you can have both mouse and joystick in one game pad at the same time (useful for some games, like Walker on Amiga).

Debugging controllers

  • Joystick actions can be viewed in serial console while running Menu core.

JammaSD arcade i/o board

MiSTer supports the use of a JammaSD by detecting if the pressed buttons are from player 1 or 2.
You first have to configure player 1 in main menu (as a joypad) (and also remap it in cores if needed).
Player 2 inputs will be auto defined, like if it was a second identical joypad.
JammaSD support was added with a VID/PID that should be the same across all devices, but if your device has a different VID/PID, you can adjust it in the MiSTer.ini file.

Choosing devices

What USB controllers can I use with MiSTer?

Most USB controllers that support HID will work with MiSTer.

There are some known issues with some famous brands which may be worth being aware of, in order to select the best options for your own preferences. More below.

What is the fastest USB controller I can get?

Almost any standard USB controller will work well with MiSTer, however there is a short list of excellent controllers that we can suggest based on user feedback and input lag testing:

  • 8bitdo M30 2.4g connected in wired mode
  • Sony DS4 in wired mode
  • Hori Fighting Commander (later revisions), either PS4 or XBOX1 variant is fine; pick your favorite
  • DIY USB adapter using open source firmware available here

Generally speaking, while Bluetooth connected devices will work fine, you can expect the highest amount of input latency while using your controller in this way.

Please keep in mind, “high latency” controllers will add, at most, 16 ms (1/60th of a second) or one frame (or rarely, depending on the controller, 32ms) of lag, and not constantly, to your experience, which is not a lot of lag, so if you’re not the type of person who notices that, you can safely just use any decent USB controller.

Please see these article for more information about USB controller lag

Gaming Keyboards, worth it?

High performance and expensive keyboards and mice aren't good for MiSTer. They won't give any benefits, so it's just waste of money. Also these devices have too many functions and many virtual devices cluttering input subsystem which may introduce input lag or be complete unresponsive. They may prevent other devices such as gamepads to work. So try to avoid these gaming Chrismas-Tree like keyboards and mice. Buy a simple one.**

PS3/PS4, XBox360/XBoxOne gamepads

These are known to have some problem with MiSTer. They have accelerometers which constantly sends the events with high rate. Analog sticks also send events even when not touched. Overall, MiSTer receives a flood of events from these controllers, and these extra events may prevent correct button definition. Games may behave incorrectly when using these controllers.

The ideal solution today for these gamepads is to use 3rd-party receivers, such as 8bitdo retro receivers, specifically the 8Bitdo Wireless Bluetooth Adapter. Not only it gives you wireless access, but also filters out all these unneeded events, while supporting Xbox One S/X, PS3, PS4, Wii, Switch, and 8Bitdo's own gamepads. One receiver will pair with one controller at one time. If multiple controllers are required for multiplayer games, then multiple receivers will need to be purchased.

The Grey/Orange (brick decorated) USB Adapters are functionally the same, after using the latest firmware. Gamepads may switch to different input modes using hotkeys for different functionality. Note that documentation on 8Bitdo's site doesn't specify this, but the update logs for the firmware updates does.

  • X-Input mode: Hold SELECT+UP for 3 seconds.
  • PSC (Playstation Classic) mode: Hold SELECT+DOWN for 3 seconds. This is useful for gamepads which are limited in buttons (12 total; DPAD counts as 4) and need to access the MiSTer OSD menu. Note that the OSD menu should not be assigned when configuring buttons in the main MiSTer menu core, as the L+R+START combination will bring up the OSD while in the cores. The combination is hard-coded in MiSTer specifically for 8Bitdo adapters. You may also lose auto-fire/mouse functionality in this mode.

Alternative 8Bitdo adapters, such as the 8Bitdo Console Retro Receiver (SNES, NES, Genesis) are always in X-Input mode when connected via microUSB.

Bluetooth Adapters and Dongles:
Any off-the-shelf bluetooth dongles will work with most wireless controllers like Dualshock4, Xbox, 8Bitdo.
See Bluetooth for details

Joystick mapping

Before using any controller with a MiSTer core, it must be defined in the main menu core

MiSTer's mapping system

MiSTer has a simple three-step mapping system:

  1. Define centrally a physical controller into a virtual "MiSTer gamepad" (+ extras)
  2. MiSTer gamepad is mapped automatically to cores1
  3. If needed, you can override at any time per core (and per controller) via OSD menu

1 - Mapping of MiSTer gamepad into cores has two "flavors" of operation, chosen by INI file. More below.

MiSTer Gamepad

The first step is to teach MiSTer to recognize your physical controller.

This is done in the menu shown at startup.

After plugging a keyboard, press F12 to show system settings and select "Define joystick buttons"

MiSTer will then ask you to assign several buttons to your controller:

  • Test the D-Pad and analog sticks (if any)
  • Four face buttons and two shoulder buttons
  • Start and Select
  • OSD button or 2-button combo (to use instead of F12 on the keyboard)
  • A few extra buttons for advanced functions (more below)

Here is a conceptual representation of the MiSTer Gamepad:

MiSTer internally recognizes more buttons (and two analogue sticks), but the above is the minimum required to work on most cores. You can also ignore the analogue stick as long as you do not use the few cores that require it (e.g. Apple II, Atari 5200).

From USB hardware to MiSTer Gamepad

This step is exclusively handled in the main startup menu. You can override it by re-doing a mapping from inside a core.

MiSTer uses USB HID to handle controllers. Each controller is recognized by a unique USB ID (VID:PID) and declares what it can do (does it have d-pad? how many buttons?). This information does not contain any physical information (which button is "A", where it is located...) and you may want to decide which buttons to specifically assign for each function.

That is where you come in. MiSTer will ask you to:

  • Test D-Pad and analogue sticks (effectively a joystick calibration)
  • Choose what to use for directions (can be D-Pad, any analogue stick, or even buttons)

Then it will ask you to assing:

  • A, B, X, Y, L, R buttons to the MiSTer gamepad (see image above)
  • Start and Select buttons
  • A button or a 2-button combo to open the OSD

And finally it will ask to select:

  • Alternative directions (also used for mouse emulation)
  • Controller buttons to use as mouse buttons (left, right, middle)
  • Button to turn on mouse emu (and to use as "sniper" mouse mode)

See below for a more technical description of each step.

During the mapping you can press:

  • ESC to cancel the mapping operation and return to menu
  • SPACE to skip a button (that button will remain undefined)
  • ENTER to end the mapping without mapping any further buttons (keeps maps done so far)

The screen will also display the VID:PID (the USB ID) of your controller.

More technical details on each step

Calibration

  • D-Pad type test This is an important step since some USB controllers generate analog events from the D-Pad, and it that case a small calibration must be done for all directions to be recognized. Simply press the RIGHT button on D-Pad first. If it generates analog stick event, then MiSTer will ask to press DOWN as a second stage. Otherwise it will proceed to the next steps if no analog event has been detected. If you are defining keyboard keys for joystick emulation, then simply press the RIGHT arrow key and it will skip Stick 1/2 steps and jump to D-Pad keys definition.
  • Stick 1 and 2 analog axes If your gamepad has no analog sticks then skip this step via the SPACE key. Otherwise, you need to define them for it to be calibrated and use proper analog to digital mapping. (Note: Some gamepads like 8bitdo M30 emulate analog stick events on DPAD, so you have to press RIGHT and DOWN for Stick 1! Skip for Stick 2). Note that these definitions have no relation to any specific mapping, it only tells to MiSTer these axes have min-0-max values with 0 as a default position and will be mapped to 2 digital buttons at the both ends. Other analog axes not defined here will be treated as 0-max with only 1 digital button.

Virtual D-Pad and Buttons

  • Right,Left,Down,Up Virtual D-Pad directions. You can use an analog stick or even buttons if desired.
  • A,B,X,Y,L,R,Select,Start. Basic buttons, any physical button can be assigned to these. Skip with SPACE if your physical controller is missing some buttons.

Alternate layout and Mouse emulation

  • Right,Left,Down,Up (Mouse and Alt) - alternative direction control. If your gamepad has analog stick, then you can assign it here. In cores this alternative control will work in parallel to the one defined in the core. So you will be able to control directions with DPAD(or whatever you've defined in core) and analog stick. Some games are good to be controlled by stick, other games are good with DPAD. These controls are used for mouse emulation as well, so if you don't have the stick (or don't want to use it), then define DPAD buttons here again. The same sticks defined here will be used for mouse emulation.
  • Mouse Left/Right/Mid Btn - buttons for mouse emulation. If your gamepad has many buttons then you can define separate buttons for mouse only, so when in mouse emulation mode both joystick and mouse buttons will be available at the same time. On reduced gamepads you may define the same buttons used for Btn1..Btn4.
  • Mouse Emu/Sniper - button to switch to mouse emulation. While holding it down gamepad will emulate the mouse. In permanent mouse mode (press OSD button while in temporary mouse mode) this button is used for smaller pointer steps (sniper mode).

System and analog stick selection

  • BUTTON OSD - important button used to access OSD menu and some additional functions.
  • Stick X/Y - analog axes. Some cores support or even require analog joystick. This allows you to define exactly which input is used for this. For gamepads this is usually the left stick.

Note: Keyboard can be used as joystick. So you have to define the keyboard as joystick in both Menu core and the core you want to use!

Mapping settings are specific to each device (identified by VID and PID). If you have several identical gamepads/joysticks then they will share the same button layout.

The number of button supported per core varies (up to 32). While defining buttons, you can press "SPACE" to skip (keep undefined) the button, "ESC" to cancel, and "Enter" to stop mapping (i.e. make the rest of buttons undefined).

Multi Button

When overriding gamepad settings inside a core it is possible to define button combinations (e.g. A+B) if you have enough physical buttons.

To allow for this, MiSTer will ask if you want to setup "alternate mappings" after defining a gamepad.

Alternate mappings are active in parallel and allow two kinds of abilities: map two physical button to the same core button (e.g. alternate button for Start), or map one physical button to two-button combo in the core (e.g. map physical X to thr core's A+B).

Bind core button to two physical buttons

The simplest is to map an extra physical button. Only this additional button needs to be defined in the alternate map, as follows:

map d-pad A B
main define Btn 1 Btn 2
alt skip skip Btn 3

The result of using this setup ia that you will have physical buttons 2 and 3 mapped to the core button B.

This also works with gamepad directions. For example, for games that use Up as a jump button, it is possible to map a physical third button to jump.

Bind physical button to core button combo

A more advanced setup is to use both mappings in parallel to make one physical button push two core buttons at the same time.

See the table below:

map d-pad A B
main define Btn 1 Btn 3
alt skip Btn 3 Btn 2

The result of this is that Button 1 will be A, Button 2 will be B, and Button 3 will be A+B.

This is particularly useful for the Neogeo core where some fighting games use A+B and C+D as "strong hit".

Bluetooth

MiSTer supports Bluetooth input devices.

Supported devices: Gamepads, Keyboards, Touch pads(as a part of multifunctional keyboard). Support for mouse and standalone touch pads is unclear. Need to be tested.

Bluetooth host must be a standalone USB BT dongle. Multifunctional dongles such as WiFi+BT probably won't work. Confirmed to work dongles based on CSR8510 and BCM20702 chips. Most (if not all) BT dongles you can buy today are based on these chips.

BT pairing dialog.

Either press and hold OSD button on I/O board for 3 seconds, or F11 key (only when OSD is active).

Pairing for gamepads and keyboards

  • Put your gamepad/keyboard into pairing mode.
  • Invoke BT pairing dialog.
  • MiSTer will try to find and pair the device (Keyboards require to enter pin 0000 and press enter).

Pairing for Dualshock 3 and Sixaxis gamepads

  • Connect the gamepad through USB to MiSTer.
  • Press PS button and wait for lights stop to blinking and only one remain active.
  • Disconnect the gamepad - lights will start to blink and then only one will remain active if succeeded.

Note: Dualshock 4 gamepad is a standard BT gamepad. So follow the first paring method.

Notes / Troubleshooting

  • Only single BT dongle is supported.
  • Depends on environment condition (how many WiFi spots and active BT devices are around) you may connect more or less BT devices at the same time. In my place i could successfully connect 3 BT devices at the same time. The 4th one couldn't be connected till i turn off one of connected. Other BT dongle allowed only 2 gamepads at the same time.
  • After MiSTer reboot many BT devices won't re-connect automatically. Some devices will shutdown them selves immediately, other devices need to be turned off manually then on.
  • Bluetooth support was added to MiSTer_20190406. Make sure to update the Linux image, menu core and mister main. As of 2019-4-17 the updater script doesn't update the Linux image by default, use the SD Installer to update the base Linux image.
  • Spotty connections and difficulty pairing have been reported with non-powered USB hubs. A powered USB hub is always recommend.
  • BCM20702 BT dongles may stuck in RF unresponsive state after reboot. From driver point of view device looks like working, but none of BT devices able to connect. Currently the only fix is to re-plug the dongle. CSR based dongles have no such issue.
  • Console/SSH bluetooth debug commands:
    • You can SSH to the MiSTer and run hcitool dev to see if your BT dongle is recognized.
    • hcitool scan will scan and print a list of recognized Bluetooth clients.
    • btpair starts the same Bluetooth pairing script accessible via F11 in the MiSTer menu.
  • MiSTer may not pair with Bluetooth controllers if other BT devices are present and scanning, such as Samsung Smart TVs. Turn these devices off to complete pairing; afterwards you can turn them back on.

Wiimote

Wiimote is supported natively from Linux release 20190510. It needs to be paired just like any other BT device. You must use red sync button on the back of Wiimite (Pairing by buttons 1+2 doesn't work!).

It's recommended to use the first Wiimote version (the one without integrated Motion Plus). This Wiimote just need to be paired once and it will automatically connect on next powering the Wiimote. Second version of Wiimote (with integrated Motion Plus, TR) is also supported but it won't be able to automatically connect later (probably due to very short time it gives to re-connect), so you have to pair it every time you want to use. 3rd party Wiimotes may or may not work, or work with problems. So it's advised to use official Wiimote.

Nunchuck and Classic Controller connected to Wiimote are supported. Mayflash Gamecube adapter for Wiimote is also supported.

To fully utilize the Wiimote you have to connect IR bar to power. You can buy a 3rd part IR bar with USB connector or modify original one to get the power from USB.

Dolphinbar

Dolphinbar is supported at some degree. You can use modes 1 and 2 as a light gun or mouse control in some cores (Wiimote is connected to P2 joystick, so you need to select Light Gun on Joystick 2 port in the core with mouse as a trigger). Mode 3 can be used as a traditional gamepad. Mode 4 (the main mode) is not supported due to absence of Linux drivers.

Overall Dolphinbar is quite useless and not recommended due to non-working mode 4. Native Wiimote support can do everything with traditional dummy IR bar.

Keyboard Handling

Keyboard

MiSTer supports keys re-mapping which is useful for reduced or localized keyboards. Key remapping is system wide, so every core will have same key map. Keep in mind it's not macro definition, so single key is remapped to another single key. Some multimedia keys generate several key codes - these keys cannot be remapped. Each keyboard model has its own key map stored in /media/fat/config/kbd_[VID]_[PID].map file. To reset all keys to default state, simply delete appropriate map file. Key remapping is available through Menu core only.

Joystick emulation

Keyboard can be switched to joystick emulation. You need to define keys used for joystick emulation the same way you did for joysticks. Auto fire is also supported the same way as for joysticks. Button defined for "KBD TOGGLE" provides a quick switch between keyboard and joystick for defined keys.

Mouse emulation

Keyboard can be switched to mouse emulation. You need to define mouse emulation buttons in Menu core the same way as for joystick.

Emulation switch

To switch between emulation modes press NumLock or ScrLock till desired mode is selected.

Switching sequence is Mouse >> Joy1 >> Joy2 >> None

LEDs on keyboard display the emulation modes:

  • Mouse emulation: NumLock LED + ScrLock LED
  • Joystick 1 emulation: NumLock LED.
  • Joystick 2 emulation: ScrLock LED.

Common functional keys/combos used in cores

  • F12 - open/close OSD menu/submenu
  • Alt-F12 - quick core selection (like in Menu core).
  • LCtrl+LAlt+RAlt - presses the "USER" button which usually is reset in emulated system.
  • LShift+LCtrl+LAlt+RAlt - MiSTer reset (load Menu core).

Notes:

  • Some systems provide writing support which requires additional attention to how you reset/shutdown the MiSTer. MiSTer tries not to keep any pending writes and writes physically to the disk as soon as possible. Still, safer way to reset the MiSTer from core which probably was writing to disk recently is using combo LShift+LCtrl+LAlt+RAlt - this will flush all caches to disk before restart. Cores without write can be restarted by hard reset button or powered down without special attention.
  • LCtrl+LAlt+RAlt sequence can be replaced by some other well known combos through INI file.

WiFi

NOTE: This page will be getting rewritten over the next few days.

For now, the easiest way to configure WIFI is by pressing the F12 button for the MiSTer menu, go to the scripts folder and run the WIFI script.

Better instructions coming soon!!

Starting from Release 20180115 MiSTer supports some WiFi USB modules.

Enable WiFi connection

  • locate the file linux/_wpa_supplicant.conf (example: /media/fat/linux/_wpa_supplicant.conf)
  • open in text editor supporting Linux/Unix line endings (for example Notepad++)
  • replace put_your_SSID_here with your actual WiFi network name and put_your_password_here with your WiFi password.
  • sometimes you need to change the country code from TW to yours.
  • rename _wpa_supplicant.conf to wpa_supplicant.conf
  • reboot the MiSTer

In Menu core you will see WiFi icon when WiFi is connected.

WiFi USB dongles Confirmed to work (running command "lsusb" on linux will show if USB ID matches)

  • ASUS USB AC53 nano rev A1.
  • D-Link DWA-171 HWVer: A1. (NOTE! D-Link DWA-171 HWVer: C1 / USB ID 0bda:1a2b does NOT work out of the box)
  • Edimax EW-7811UN (USB ID 7392:7811)
  • Edimax EW-7822ULC (USB ID 7392:b822, 5ghz capable)
  • Edimax EW-7612UAn V2
  • TP-LINK TL-WN823N V2 (needs copy rtl8192eu_nic.bin to /lib/firmware/rtlwifi)
  • CanaKit USB WiFi dongle - Works out of box (USB ID: 148f:5370, driver: rt2800usb, firmware: rt2870.bin)

Some WiFi firmwares can be found here: https://github.com/wkennington/linux-firmware

Compiling and installing custom WiFi drivers

Instructions for rtl8188fu based adapters (like the Zapo RTL8188 USB stick) can be read here:

MiSTer custom WiFi driver compilation

Steps can be adapted for other WiFi adapters.

FTP, SSH/SFTP

Network access

MiSTer board can be access through on-board Ethernet port. System has FTP, SSH, SFTP services running.

User name: root Password: 1

By default, DHCP is used to acquire an IP address for the board. You can find it from your router (easier way), or from console connected to the board using the command ifconfig

The default MAC address for the on-board Ethernet port is 02:03:04:05:06:07. Please consider this when connecting more than one MiSTer board via the on-board Ethernet port to your network.

TODO: How to setup a custom MAC address.

Setting up a static IP address

Currently the best way to do this is using connmanctl (try connmanctl help for more info).

  • Find your on-board network service name.
    # connmanctl services
    *AO Wired                ethernet_020304050607_cable
  • Setup IP address (e.g. 192.168.1.123, should be unused), subnet mask (e.g. 255.255.255.0) and gateway (e.g. 192.168.1.1, typically your router IP address). To configure the right device use the service name returned from above command (e.g. ethernet_020304050607_cable). This will disable the use of DHCP.
    # connmanctl config ethernet_020304050607_cable --ipv4 manual 192.168.1.123 255.255.255.0 192.168.1.1
  • Setup one or more DNS server(s) (e.g. 192.168.1.1 from your router, 8.8.8.8 from Google DNS.
    # connmanctl config ethernet_020304050607_cable --nameservers 192.168.1.1 8.8.8.8

You can write a script to help with typing and remembering your settings.

You can also setup your on-board network connection by editing /etc/network/interfaces. This is currently not advised. Because if you have a DHCP server in your network, the network stack will still contact the DHCP server and assign the returned IP address regardless, leading to usually unwanted behavior.

(Re)Enabling DHCP

# connmanctl config ethernet_020304050607_cable --dhcp

Other

mc (midnight commander) file manager is available for easier folder navigation.

The root of SD card: /media/fat

Related: Serial Console Access

Samba / Windows Network Shares

You can access the MiSTer through Samba network. This is native protocol for Windows shares. MiSTer already has FTP and SSH services, but Samba has a special feature - Windows treat Samba shares as a local filesystem. For example, if you want to view or edit the file, then you need to download it fully first in case of FTP/SFTP access. With Samba, only small required portion if file will be loaded. If file has size of 100MB - it makes big difference. Similarly, if you want to use a HEX editor, you don't need to download the whole file. Just open it in HEX editor and only small portion will be loaded where you can quickly edit required bytes and save it back quickly. Basically, work with remote files as quick as with local files if you don't need the whole content. With Samba access you can mount VHD files on your PC without downloading! Using utility ImDisk you can mount VHD files as a local disk (mount it as removable store for easier un-mounting).

Notes:

  • By default Samba service is not active. You need to rename /media/fat/linux/_samba.sh to linux/samba.sh, then edit this file if you need specific user name and password (default is user root with pass 1) and then reboot the MiSTer.
  • you can access the MiSTer either by IP address or by name \\MiSTer (or \\mister - case insensitive).
  • Make sure you've closed all opened remote files and un-mounted all remote VHDs before restarting the MiSTer or start the cores using the same VHDs in order to prevent the data corruption!
  • This can also be accessed from FTP by using IP address, login user name root with pass 1.
  • MiSTer's default samba workgroup is MiSTer. Usually you will not need this to log in.

Troubleshooting:

If you're using a Windows OS (Vista and above) while trying to access the share and the credentials do not work, there may be a possibility that the LAN Manager authentication level is not being worked out correctly between the Windows OS and the Samba daemon on MiSTer.

The error message may manifest itself as a The specified network password is not correct error. A fix is to lower the Samba NTLM authentication level on the MiSTer to NTLM v1.

This is done with the following steps:

  1. SSH into your MiSTer instance.
  2. Edit the Samba configuration file.
    nano /etc/samba/smb.conf
  3. Append under global, where the keyword yes signifies ntlmv1-permitted, which allows for NTLMv1 and above for all clients (against MiSTer). By default the value is not set explicitly and is no, which equates to ntlmv2-only. Further information is specified in the ntlm auth (G) section at https://www.samba.org/samba/docs/current/man-html/smb.conf.5.html.
    [global]
    min protocol = SMB2
    ntlm auth = yes
  4. Reboot MiSTer or restart the Samba daemon.
    /etc/init.d/S91smb restart
    You should see no errors when manually restarting. e.g.
    /root# /etc/init.d/S91smb restart
    Shutting down SMB services: OK
    Shutting down NMB services: OK
    Starting SMB services: OK
    Starting NMB services: OK
    Alternatively, on the Windows OS, change the Windows registry HKLM\SYSTEM\CurrentControlSet\Control\Lsa\LMCompatibilityLevel to 3. Note that you may/may not have permission depending on your security policy or Administrator rights. This is described by Microsoft at https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/network-security-lan-manager-authentication-level.

Internet for Amiga/ao486

Starting from 2018 may 7 release MiSTer supports serial (UART) connection from FPGA to Linux. Linux OS runs PPP or Console daemon on this connection allowing access the internet or Linux shell from FPGA cores.

Cores supporting serial connection

  • Minimig. Tested on Roadshow TCP/IP, AmiTCP and Miami. AmiTCP provides more complete solution with ftpd daemon. There are many other 3rd party addons are based on AmiTCP, so it's advised to use this package. Roadshow works ok locally, although i couldn't make DNS work. Probably it needs more settings, but their 20min demo doesn't allow to test and setup it fully. Miami was successfully tested. The Miami settings that worked: use PPP connection via serial.device, set baud rate to 115200, RTS/CTS to on, and enable 8N1. Set modem to nullmodem. Manually enter an IP suitable for your lan ending in 254, e.g. 192.168.1.254. Manually add a DNS server, e.g. 8.8.8.8 for Google DNS. Term v4.7 has been used to test console connection.
  • ao486. Currently only console connection has been tested using Dos Navigator's integrated Terminal and Kermit 3.15. PPP should work under Win95. DOS tools are here : dos_ftpd.zip. The DOS FTP server included does not support passive mode, so set your client to use active.
  • C64. Serial connection.

OSD provides an option to switch between PPP and Console on these cores. Both console and PPP are using baud rate 115200 8N1 mode with hardware RTS/CTS flow control for stability.

Console connection

Using this connection with supported terminal application on FPGA core, you can access the Linux shell and do some file managements or Linux settings if required. No special settings are required of Linux.

PPP connection

Using this connection core may have internet connection. More important, the core may run ftp daemon and provide access to its filesystem, so you can use FTP client on PC to move the files to/from the emulated system.

PPP daemon uses /media/fat/linux/ppp_options (linux\ppp_options of PC) file. Most likely you don't need to modify it. Recent update assigns IPs automatically. Core gets <your_net>.254 IP (for example 192.168.1.254). If you want other IP, then modify ppp_options file. For correct PPP work, make sure you see a network icon in Menu core before starting the other core. Otherwise PPP link won't get IPs. If you've started core earlier, then simply connect the core to PPP and disconnect. Next connection will get correct IP. Or you can switch UART mode in OSD to renew the IP.

NOTE: I'm looking Amiga and MSDOS terminal supporting color and control codes of linux, so it will be possible to use Midnight Commander in terminal connection. If you know such terminal application, then let me know.

PPP connection in Windows 95 on ao486

Unfortunately winsock and winsock2 provided by Microsoft do not work with the ppp connection when in Windows 95. The following steps will allow you to get it working.

  1. In the Mister System Menu ( Win/F12 ) set the "Uart Connection" to "PPP" and save it.

  2. In Windows 95 ensure the COM1 device is installed in Start->Settings->Control Panel->System


    Device Manager Tab, there should be a twisty called Ports(COM & LPT) and under that a "Communications Port (COM1)"

  3. If it doesn't exist go to Start->Settings->Control Panel->Add/New Hardware and it should be automatically added.

  4. Get the replacement PPP client
    Download the software. There are other newer versions available BUT be warned only version 3.0 will work.
    Trumpet Winsock 3.0 or Official Homepage
    (I extracted the file from the disk image and uploaded it using the DOS ftp client documented above)

  5. License the Software
    This software is still shareware (time limited) please license it appropriately. Once you acquire a license you can put the details in Tcpman in the "Special" menu in "Password registration"

  6. Configure Software

    1. Start Tcpman

    2. Under File->PPP Options ensure all checkboxes are unchecked and the text boxes are blank.

    3. Under File->Setup Enter an "IP Address" suitable for your LAN eg 192.168.1.254 and a "DNS Server(s)" 192.168.1.1


      Under the Driver section select the PPP radio button and click on "Dialer settings..."

    4. In the "Dialer settings..."


      "COMM port" COM1


      "Baud rate" 115200

  7. Using the software ( important, be patient )


    Win95 is rather slow so let it start fully before starting the PPP manager (Tcpman)


    Once it is started it will begin syncing with PPP on the linux host . . . Be patient it takes a few seconds.


    When you see the PPP[C021] SND and RCV you can start your TCP/IP program

I have found it to be a little complicated to get started, but once it is running it is rock solid and supports multiple client programs at once.

Serial connection on C64

The following is an example for connecting to a BBS using Striketerm 2014.

  1. Start the C64 core (please note that custom kernels may remove functionality required, if in doubt use the built in kernel).

  2. In the Mister C64 Menu ( Win/F12 ) set the "User Port" to "UART", and save it.

  3. In the Mister System Menu ( Win/F12 ) set the "Uart Connection" to "Midi", "Remote", "TCP" and save it.

  4. Load Striketerm 2014 from d64. Available from here

  5. Keep the defaults in the Main Menu (F1), ensure you are running at 2400 baud.

  6. Save a BBS into the Addressbook (F5), you can get some from here

  7. Surf the BBS very slowly . . .


Console connection (Serial UART)

The DE10-nano board has console port. The console allows you to login into Linux without a network connection and also provides some debug/info which sometimes useful to track the problems.

Refer to the UART-to-USB (USB Mini-B) connector on the board right side in the picture below:

How to connect

Connect the DE10-nano board to a PC using the UART-to-USB (USB mini type B) connector next to micro-USB. The PC will recognize it as virtual COM port. Use any console application to connect to this COM port. I recommend Putty.

Verify that COM port settings are correct:

  • Speed (baud rate) - 115200 bits per second
  • Data bits - 8
  • Stop bits - 1
  • Parity - none
  • Flow control - none

Linux Connection

  1. Be sure to be a member of the dialout group.
  2. Your serial port is likely to be /dev/ttyUSB0
  3. Configure it: $ stty -F /dev/ttyUSB0 115200 cs8 -cstopb -parenb -ixoff -ixon
  4. Look at the output while dumping it to a file: cat /dev/ttyUSB0 | tee mr.log

Now mr.log has a copy of all the information shown in the screen.

U-Boot command prompt

To interrupt u-boot and get into the u-boot command prompt once connected to the DE10-Nano, hold 'ESC' on the PC and then power on or reboot the Nano (using the reset button). Startup should be interrupted and you should see a '=>' prompt. Here you can edit the kernel boot options etc.

Cheat Engine

Setup

Cheats should be stored in: cheats/system/rom_filename.zip where system is name of the core like NES, SNES, Genesis, etc..

So, for example: cheats/NES/Taboo (USA).zip for the NES ROM Taboo (USA).nes

The filename of the zip must match the ROM name exactly. Cheats will be loaded automatically when you load a ROM, and can be enabled and disabled from the menu in supported cores.

If the .zip cheat file does not match the ROM name, the cheat engine will automatically check the ROM CRC32 and select the appropriate .zip cheat file with matching CRC32 accordingly. ROM name matching has priority over CRC32 checking.

Individual cheats are in .gg format and should be stored in zip files. Packs of codes can be downloaded from https://gamehacking.org/ by selecting the MiSTer format and choosing to save all codes for a given game.

Making your own codes

All types of cheat codes for 16 bit systems and earlier can be decoded into four pieces of information: An address, a compare value, a replace value, and usually a flag to say if the compare value is used or not. The format for a gg file is in binary as 4 32 bit integers in little-endian byte order.

For example, if the Address is 0xFF1CA0 and the compare value is 0xB5 and the replace value is 0xFF, the file would look like this:

01 00 00 00 A0 1C FF 00 B5 00 00 00 FF 00 00 00

The first four bytes are little-endian 0x00000001 for "compare enabled", the second four are little-endian address, third set are compare value, and fourth is replace value. Note that not all codes use a compare value.

For cheats with multiple codes, simply add another 16 bytes at the end of the file in the same format as the first.

You can decode game genie codes into these values with tools like this: https://gamehacking.org/system/nes

Video Filters

Introduction

If you use MiSTer you should be using a custom filter for upscaling if you want high quality without uneven scaling and shimmering during scrolling.

The MiSTer Filters and Gamma Github repository is here: MiSTer Filters and Gamma Github

As of November 2018, MiSTer can use custom filter coefficients to define the interpolation used for scaling over the HDMI output (and VGA too with a mister.ini option). This allows MiSTer to scale images using well-known image scaling algorithms such as bicubic or lanczos scaling as well as other scaling methods better suited to scaling pixel graphics. Special effects such as scanlines and lcd effects are also possible.

This github repository houses all of the Interpolation Filters that have been created so far for MiSTer: MiSTer Filters/Gamma Github Repository

As of November 2019 this github also contains Gamma Lookup Tables to allow MiSTer apply a gamma curves to cores with an updated framework. James-F has created a number of curves that are included in the Gamma folder of this repository.

How to use filter coefficients and gamma tables

To use any of the pre-made filter coefficients (or your own) you need:

  • An updated version of MiSTer (Main_MiSTer). The first release with support was MiSTer_20181116.

  • A supported core. Nearly all cores should have support now, but some Arcade Cores still have not been updated to the newer MiSTer framework as of November 2019.

  • Filters. Filters are text files containing the coefficients for a specific interpolation method. All filters must go in the Filters directory on your MiSTer SD card. The most common way to obtain a set of filters is to run the MiSTer updater script (if your MiSTer has network access). You can also download a release ZIP file from this repository or download a copy of this repository and copy the Filters folder over to your SD card by hand.

Filter Releases are here: MiSTer Filters/Gamma Release Folder

  • Gamma. Gamma tables are text files containing the R,G,B entries of a gamma lookup table. All gamma LUTs must go in the Gamma directory on your MiSTer SD card. You can obtain gamma tables in the same way as the filters: either using the MiSTer updater script or by copying the Gamma folder from this repository over to your SD card by hand.

Once you have updated MiSTer and Cores and your filter/gamma coefficients in the right place you simply

  • Start a supported core
  • Go to page 2 of the core's OSD menu and under HDMI Scaler: change the option from "Filter - Internal" to "Filter - Custom"
  • The option below "Filter - Custom" should now be enabled and will allow you to choose your filter from the files in your /Filters folder.
  • Gamma Tables are implemented the same way and are just below the Filters options on page 2 of the OSD. If you have Filters settings but not Gamma settings then you're using a core that does not yet support Gamma LUTs.

Frequently Asked Questions

Q: What filters should I use?

A: Use "Interpolation (Sharp)" and "SNES Interpolation (Sharp)" if you don't care for scanlines and just want good interpolation.

But all of the filters Filters root are "Recommended Filters". So Interpolation (Sharp), Scanlines (Sharp), Scanlines (Soft), Vertical Scanlines (Sharp), Vertical Scanlines (Soft), LCD (Monochrome), and LCD (Color) are good defaults for most MiSTer cores.

Q: Why would I want to use custom filter coefficients?

A: The default scaling algorithm of MiSTer is Nearest Neighbor/Lanczos and is not ideal for upscaling pixel graphics. The filters allow much better looking scaling and special effects such as scanlines.

Q: Doesn't MiSTer already have scanlines through the "Scandoubler FX" option in the OSD?

A: Yes, but the scanlines available with "Scandoubler FX" are aligned to the scandoubled image and the scanlines through the filter coefficients are aligned to the original pixels in the scanline. So you achieve better scanlines with filter coefficients in most cases.

Q: Where do I get sets of Filter Coefficients or Gamma LUTs?

A: Here. Or the update script which will get them from here. This is the official place to get these filters as of Dec 03, 2018

Q: Why are some filters labeled "SNES"?

A: MiSTer's SNES core outputs a 512 pixel wide image even when the SNES is in it's 256 pixel wide mode. This makes the horizontal interpolation too sharp. The SNES specific filters take this into account.

Q: What do some filters have "NN" appended to the name?

A: Some people set MiSTer to scale to do integer scaling for the vertical upscaling (by setting vscale_mode=1 in mister.ini). If you do this you can use the "NN" filters that only enable interpolation for horizontal scaling.

Q: Where is a filter that does XXXXX?

A: Check the subfolders for many filters. Only a few are in the Filters root folder to make choosing a filter easier for newbies and non-technical people. But there are many more to choose from.

What do some filters look like?

The Filters folder contains a set of recommended filters for general use. There are samples in the Samples folder of this repository. View these images at full size to make a proper evaluation.

Interpolation (Sharp):

Scanlines (Sharp):

Scanlines (Soft):

LCD Effect (Monochrome):

LCD Effect (Color):

Vertical Scanlines (Soft):

Technical Information

The commercial VIP scaler implements a generic 4 tap, 16 phase polyphase filter. The open source ASCAL scaler that MiSTer uses now implements the same type of filter for scaling. Details are on page 189 of the VIP scaler docs here: Intel VIP Scaler Doc

The Zipcores Application Notes pdf explains the workings of the filter much better than the ALtera/Intel docs: Zipcores Application Notes

Most of the currently available filter coefficients were generated with the Matlab code here: https://github.com/ghogan42/Filter-Coefficients-For-MiSTer

Tips for understanding the MiSTer filter coefficient text files:

  • There are separate coefficients for horizontal and vertical scaling.
  • Each row of the Filter Text File list the coefficients for taps T0, T1, T2, T3 for a paricular phase.
  • The first row is phase 0 and corresponds to the center of tap T1.
  • The ninth row is phase 8 and corresponds to the halfway point between T1 and T2 (so it's the pixel edge between T1 and T2).
  • Then last row is phase 15 and corresponds to 15/16th of the way from T1 to T2 (so one phase before the center T2).

Sample Coefficient Set. Note the following:

  • This is a 2 tap filter because we only have non-zero coefficients for taps T1 and T2
  • The vertical coefficients don't sum to 128 for the middle phases. Since they sum to less than 128, the output will be darker. That's how scanlines are implemented.
# range -128..128
# sum of line must not exceed the range!

# Sharp Bilinear on x-axis and y-axis
# 40% Scanlines on y-axis

# horizontal coefficients
   0, 128,   0,   0
   0, 128,   0,   0
   0, 127,   1,   0
   0, 125,   3,   0
   0, 120,   8,   0
   0, 112,  16,   0
   0, 101,  27,   0
   0,  85,  43,   0
   0,  64,  64,   0
   0,  43,  85,   0
   0,  27, 101,   0
   0,  16, 112,   0
   0,   8, 120,   0
   0,   3, 125,   0
   0,   1, 127,   0
   0,   0, 128,   0

# vertical coefficients
   0, 128,   0,   0
   0, 126,   1,   0
   0, 116,   5,   0
   0, 102,  10,   0
   0,  86,  16,   0
   0,  71,  21,   0
   0,  57,  26,   0
   0,  46,  31,   0
   0,  38,  38,   0
   0,  31,  46,   0
   0,  26,  57,   0
   0,  21,  71,   0
   0,  16,  86,   0
   0,  10, 102,   0
   0,   5, 116,   0
   0,   1, 126,   0

Audio Filters

Temporary quick introduction

Cores need to be update with new framework. Cores released from 2020/06/18 and later should support audio filters. Filter setting files should be placed into Filters_Audio Each file is simple text file with extension txt. Example of filter file:

# version
v1

# sampling frequency
# must be multiple of 48000 for best results
7056000

#base gain
0.00000316778645516#gain scale for X0
2

#gain scale for X1
1

#gain scale for X2
0

#coefficient for Y0
-1.9974813602

#coefficient for Y1
0.9974845280

#coefficient for Y2
0

Screenshots

MiSTer has the ability to capture screenshots of a running core. This is useful for many things, including "saving" passwords.

Press Win + Print Screen (⌘ + F13)

The snapshots are captured directly from the core video output before it is scaled and any filters are applied -- i.e., it saves at the core's native video resolution.

Output files are stored in /media/fat/screenshots/

Desktop Linux

Here is the release with full-featured Desktop Linux with GUI and Update 20180502 (custom video mode support)

Make sure you use MiSTer Linux release from 2018 Apr 7 or later. Extract the archive to the root of MiSTer SD card FAT partition.

Desktop Linux is based on Ubuntu 16.04 with LXDE distributed by Terasic with DE10-nano board. It's light-weight linux. Frame buffer has been completely rewritten with configurable resolution and integrated scaler. Audio output is also implemented unlike original Terasic version. VGA and all MiSTer audio outputs are supported.

How it works? If core (rbf file) has the text file with the same name, then it means MiSTer will reboot and will use additional sets of u-boot commands from that txt file. That's how alternative kernel and linux image are used. It's not really tied to Linux only. If there will be other cores requiring special code on ARM side, then it will be run the same way. Even bare-metal projects can be loaded.

One RBF file can have several configs using RBF as a base name + additional suffix. Several configs are included in release. Video card emulated in FPGA has 2 resolutions:

  • HDMI resolution comes from the the board to HDMI and VGA.
  • Linux resolution which Linux sees. It will be boxed and then up/down scaled to HDMI resolution.

Thus Linux may have any resolutions up to 1920x1080, including non-standard ones.

All video parameters are passed as kernel parameters in config file (txt). Parameters are:

  • altvipfb.video_mode - video mode number. Same as in MiSTer.ini (including custom modes, new format). Default is 1280x720@60
  • altvipfb.aspect - set to 0 if you want to stretch Linux resolution to full screen. By default aspect=1. If bgwidth or bgheight are set, then aspect ratio is ignored in favor to explicit box dimensions.
  • altvipfb.width - horizontal resolution for Linux. Default is the same as HDMI resolution width.
  • altvipfb.height - vertical resolution for Linux. Default is the same as HDMI resolution height.
  • altvipfb.format - color format. Default is 8888 i.e. 32bit. Other possible values are 565 and 1555 - both are 16bit colors. 565 is good alternative to 8888. It requires 2 times less memory and works faster than 32bit.
  • altvipfb.bgr - set to 1 if you want to swap R and B components. Usually you don't need to use this parameter. Default is 0.
  • altvipfb.bgwidth - box width. Default is the same as width.
  • altvipfb.bgheight - box height. Default is the same as height.

Box resolution is added around Linux resolution before up/down scaling. It's used to add horizontal/vertical fields in order to correct aspect ratio - i.e. letterboxing. By default Linux resolution will be boxed automatically, so bgwidth/bgheight usually are not required.

Check supplied config files to see how to use the parameters. Leave other text as-is if you don't know what it does. Text file uses Linux line endings, so you need to use compatible text editor if you edit it on Windows PC.

Note: Linux image is mounted as read-write, so avoid from turning off or reset without proper shutdown! I suggest to choose "Reboot" instead of "Shutdown" so MiSTer will reboot into MiSTer menu where you can simply turn off the power. DE10-nano board has no power off feature, so if you choose "Shutdown" it will end by black screen and it will be hard to tell if shutdown procedure is finished already or not. Every reboot from Linux will reboot to Menu core.

MIDI

When running the Minimig and ao486 cores, once a ALSA compatible USB MIDI device is attached, two additional ‘UART Connection’ menu options (‘USBMIDI’ and ‘USBMIDI-38K’) will be available in addition to ‘None’, ‘PPP’ and ‘Console’.

Minimig

‘USBMIDI’ - This option is used with the Amiga / Minimig core. This option sets the UART connection speed to 31250 baud which is the standard MIDI speed.

Many Amiga applications and most games don’t require any additional drivers for MIDI. Some “newer” applications may require the CAMD driver.

Aminet : CAMD

ao486

‘USBMIDI-38K’ -This option is used with the ao486 core. This option sets the UART Connection speed to 38400 baud. (The MIDI speed of 31250 baud is not a standard speed DOS PC UARTs were capable of doing)

While some sequencer applications and Microsoft Windows may support MIDI on the serial port, DOS games typically require a MPU-401 interface which ao486 unfortunately lacks. In lieu of hardware MPU-401 capability the SoftMPU TSR can be used with a good degree of success.

SoftMPU

SoftMPU

SoftMPU requires the QEMM memory manager be installed. For testing QEMM 8.03 was used. QEMM “stealth” option seems to be incompatible with ao486 so it is advisable to skip that part of the optimize process. It’s a good idea to run the QEMM optimize application again after installing SoftMPU (in the AUTOEXEC.BAT) to get as much of the lower 640K conventional RAM free as possible.

Although less common, some DOS games and applications require MPU-401 interrupts. This option can break compatibility with others software not requiring interrupts.

Starting SoftMPU without MPU-401 interrupts:

   SOFTMPU.EXE /MPU:330 /OUTPUT:COM1

Starting SoftMPU with MPU-401 interrupts:

   SOFTMPU.EXE /SB:220 /IRQ:5 /MPU:330 /OUTPUT:COM1  

The Rev.0 Roland MT-32 used in testing required the ‘DELAYSYSEX’ switch to prevent buffer overflow for certain games but made Sierra games upload sysex commands excessively slowly. This is not necessary for General MIDI modules and newer revision MT-32s.

   SOFTMPU.EXE /MPU:330 /DELAYSYSEX /OUTPUT:COM1

The 'midilink' daemon currently supports following switches / options:

   TESTSER  - this option sends a test message to the serial port once 
              the daemon is started.  

   TESTMIDI - this option sends a middle 'c' note to the MIDI device 
              once the daemon is started. 

   QUIET    - this option suppresses MIDI debug output.  

   38400    - this option sets the serial speed to 38400 baud 
              (default is 31250 baud) - used with ao486 core.

MidiLink Github

MIDI Adapters reported to work:

   * Creative EMU XMIDI - Known to mangle SYSEX messages
   * Roland UM-ONE
   * M-Audio Midisport Uno

Customizing your setup

The MiSTer menu can be customized in a number of ways.

eg You can add a cool font, or change the background image for the main menu.

To change the default font

Create a /media/fat/fonts folder on your SD card.

Next download the fonts from here - MiSTer Fonts

Copy the pf files downloaded from that url to the /media/fat/fonts folder

Next edit /media/fat/MiSTer.ini

Find the

font= line, and edit to use a new font. Be careful not to add a / before the font folder!

eg

If you want to use the C64 font - change the font line to

font=fonts/Computer_C64.pf

To add a background image

Find a suitable png or jpg file that you like

Copy your desired image to /media/fat/menu.jpg or /media/fat/menu.png (as appropriate)

reboot

Press F1 once rebooted into MiSTer to select your background.

To use multiple background images

There is also a way to have MiSTer choose from a selection of wallpaper images at random. On the root of your micro SD card (/media/fat), you can create the following folder:

wallpapers

Remove the menu.jpg/menu.png file (if present) from the root of the micro SD card. Populate the wallpapers folder with your desired images. Press F1 to cycle through the included default images until you see one of the custom wallpaper images you have added, then leave it on that image. On the next restart, a different image will be chosen at random.

You can also create the following additional folders:

wallpapers_alt_1 wallpapers_alt_2 wallpapers_alt_3

MiSTer supports up to three additional configuration profiles. The active MiSTer.ini or MiSTer_alt_*.ini file will determine from which folder the images are selected. If any of your configuration profiles use different resolutions, you can populate the corresponding wallpapers folders with only images of that profile's resolution. Each of these folders can have completely unique multiple images, or you can place just one image in each folder to have greater control over which background is used for certain configuration profiles.

Arcade Roms

Configuring Arcade Roms

MRA Format

Because some arcade boards can change games by just putting in new roms, it made sense to move the RBF files out of sight from the menu list, and browse the MRA files instead. These MRA files specify which RBF file to use, and which mame rom zip files to create on the fly into a rom to pass to the arcade core. They will create the old a.pacman.rom style rom on the fly from mame roms, either merged or non-merged.

Here is an example of where the files might go:

/_Arcade/<game name>.mra
/_Arcade/cores/<game rbf>.rbf
/_Arcade/mame/<mame rom>.zip
/_Arcade/hbmame/<hbmame rom>.zip

There are other locations for these files based on search paths.

MRA Format

<misterromdescription>
  <name>Donkey Kong (US set 1)</name>
  <mratimestamp>201911270000</mratimestamp>
  <mameversion>0216</mameversion>
  <setname>dkong</setname>
  <year>1981</year>
  <manufacturer>Nintendo of America</manufacturer>
  <category>Maze / Monkeys</category>
  <category>Platform</category>
  <category>Platform / Mario Bros.</category>
  <rbf>DonkeyKong</rbf>
<!-- switches element taken from "Pac-Man (Midway).mra"; for demonstration purposes only -->
  <switches default="FF,FF,C9">
    <dip bits="15"    name="Cabinet" ids="Cocktail,Upright"/>
    <dip bits="16,17" name="Coinage" ids="2c/1cr,1c/1cr,1c/2cr,Free Play" values="3,1,2,0"/>
    <dip bits="18,19" name="Lives" ids="1,2,3,5"/>
    <dip bits="20,21" name="Bonus Life After" ids="10000,15000,20000,None"/>
    <dip bits="22"    name="Difficulty" ids="Hard,Normal"/>
  </switches>
  <buttons names="Jump,Start 1P,Start 2P,Coin" default="A,Start,Select,R"/>
<!-- rom index 1 or any other index can pass additional information to a rom.
useful to say this rom is game A or game 1.  Use it in case of multiple games for
the same RBF, ie: Dig Dug 2, Mappy -->
  <rom index="1">
    <part>0A</part>
  </rom>
<!-- romstruct element taken from "Two Tigers.mra"; for demonstration purposes only -->
  <romstruct>
ROM structure
00000 - 0BFFF  48k CPU1
0C000 - 0FFFF  16k CPU2
10000 - 13FFF  16k GFX1
14000 - 1BFFF  32k GFX2
  </romstruct>
<!-- rom index 0 is the standard rom. The zip will be added to the name inside the part, unless the
part has it's own zip. The md5 will be checked at the end. A file not found error is reported before an md5
error. -->
  <rom index="0" zip="dkong.zip" md5="05fb1dd1ce6a786c538275d5776b1db1" type="merged|nonmerged|split">
    <part crc="ba70b88b" name="c_5et_g.bin"/>
<!-- interleave element taken from "Crater Raider.mra"; for demonstration purposes only -->
    <interleave output="32">
    <part crc="579a8e36" name="crvid.a4"  map="0001"/>
    <part crc="2c2f5b29" name="crvid.a3"  map="0001"/>
    <part crc="5bf954e0" name="crvid.a6"  map="0010"/>
    <part crc="9bdec312" name="crvid.a5"  map="0010"/>
    <part crc="4b913498" name="crvid.a8"  map="0100"/>
    <part crc="9fa307d5" name="crvid.a7"  map="0100"/>
    <part crc="7a22d6bc" name="crvid.a10" map="1000"/>
        <part crc="811f152d" name="crvid.a9"  map="1000"/>
    </interleave>
<!-- begin kill screen fix -->
    <patch offset="0xf7d">
FE 04 38 02 3E 04 47 A7 17 A7 17 A7 17 80 80 C6 
28
    </patch>
<!-- end kill screen fix -->
    <part crc="d6412358" name="c-2j.bpr"/>
    <part crc="b869b8f5" zip="another.zip" name="v-5e.bpr"/>
    <part crc="b869b8f5" name="v-5e.bpr" offset="1024" length="1024"/>
    <part repeat="3328">00</part>
    <part>
80 80 80 80 80 80 7F 7F 7F 7F 7F 7F 7F 80 80 80
    </part>
  </rom>
<!-- If the first rom0 fails the md5 checksum, it will go ahead and try again if another entry is present.
Otherwise it will skip the additional entries.
-->
  <rom index="0" zip="dkong.zip" md5="05fb1dd1ce6a786c538275d5776b1db1">
  </rom>
</misterromdescription>

When creating a core you can pass additional data in using ioctl_index > 0.

// Retrieve Title No.
always @(posedge clk_sys) begin
   if (ioctl_wr & (ioctl_index==1)) tno <= ioctl_dout[3:0];
end

Explanation for XML elements and attributes

  • name: As an element this indicates how the rom should be called. The value should be taken from MAME. As an attribute this indicates an external rom file (or part thereof) that should be loaded by MiSTer.
  • mratimestamp: This indicates the date on which the .mra file was created (useful for other users to determine if there is a newer version of the .mra file available to which they should upgrade). The date format is yyyymmdd.
  • mameversion: This indicates on which version of a MAME romset the *.mra file is based (which version was used for testing). The dot in MAME's version numbering is omitted.
  • setname: This indicates the name of the romset used as given by MAME. It is used to overwrite the core ID specified in the *.rbf file so that individual settings can be saved on a per romset basis.
  • year: This indicates the year the game was released. The format is YYYY and the value should be taken from MAME.
  • manufacturer: This indicates the manufacturer of the game. The value should be taken from MAME.
  • rbf: This indicates the filename (sans path and extension) of the core that should be used to run the game.
  • buttons: This indicates the default button mapping for the game. As the name implies, it only implies to buttons, not to directional controls. The names attribute specifies how the buttons are called in the MiSTer OSD while the default attribute specifies how the buttons are mapped to the virtual MiSTer gamepad.
  • switches: This is to define the dip switches present on the arcade board. As this is a bit more complex, there is a specific section for it below.
  • romstruct: This is to give information about the rom structure, how the rom memory is mapped. Information contained herein is intended as a comment for other developers and not actually used by MiSTer.
  • remark: This element is intended for general remarks. Information contained herein is intended as a comment for other developers and not actually used by MiSTer.
  • rom: Part, patch and interleave elements must have a rom element as a parent element. An index attribute with a value of 1 is used to pass information to multigame cores, which machine configuration to use. For passing actual rom data you need an index value of 0. The md5 attribute is used to specify the md5 checksum. The md5 checksum is calculated and checked by MiSTer after the whole rom is created according to the given .mra file. You can use the Linux console to find out the checksum calculated by MiSTer. Roms whose checksum differ from the one specified in the .mra file won't load.
  • part: The part element is only allowed inside a rom element. It is used for specifying a part of the rom. The content of a part can either be embedded as a hex value into the .mra file itself (if copyright law allows) or there can be a reference to an external file via the name attribute. If the external file is in a different zip file than the parent rom element, the filename of the zip file must be specified via the zip attribute. The crc attribute specifies the CRC32 checksum of the respective part (format: eight hex digits). If a crc value is specified, MiSTer will try to select the appropriate file by crc (and only revert to the filename specified by the attribute name, if the crc value does not match). This increases compatibility of the .mra file with different MAME versions of the romset. As crc values are only relevant for external files, a crc value should only be given to a part element when there is a reference to an external file. The repeat attribute only applies to embedded parts and indicates for how long (not how many times) the sequence should be repeated. By default decimal numbers are assumed. Hex numbers must be preceded with "0x". Inside the rom element, the offset- and length attributes only apply to external files. To use the offset attribute for internal data, the patch element must be used. Offset indicates the location inside the file from where MiSTer should start reading and length indicates the length of the sequence that MiSTer should be reading. By default decimal numbers are assumed. Hex numbers must be preceded with "0x". The map attribute specifies to only read certain parts of the corresponding part element. For example a value of "0001" (binary) means to read only every fourth byte while a value of "1010" (binary) means to read only every first and third byte. To byteswap a part you need to set a map attribute value of 21 (decimal) and enclose the respective part element in an interleave tag.
  • patch: The patch element is only allowed inside a rom element. It is applied after the whole rom is created from its parts and overwrites the content of the rom with the content of the patch element, starting from the specified offset and for the length of the patch element's content.
  • interleave: The interleave element is only allowed inside a rom element and can only be used as parent element to one ore more part elements. Together with the mandatory output attribute the interleave element can be used to specify that the children part elements should be read in a certain way. For example an output-value of "32" (decimal) indicates that the children part elements ROM data should be treated as 32 bit.

Dip Switches

Dip switch support in the latest version of MRA is used instead of the status bits. The DIP config str is listed in the core, and the core is responsible for reading the up to 64bits of dip data that is sent via ioctl_index 254.

reg [7:0] sw[8];
always @(posedge clk_sys) if (ioctl_wr && (ioctl_index==254) && !ioctl_addr[24:3]) sw[ioctl_addr[2:0]] <= ioctl_dout;

Switches is the dip switch setting. The default are the default bytes. These are used so you can default the arcade into the proper factory settings. This is useful when the factory settings aren't all OFF/OFF/OFF.

 <switches default="FF,FF,C9">

The dip tag let's you put in a dip switch entry. The bit number (starting at 0) is based on the way the core was written. Often MAME source code can be used to understand the bits. The numbering will depend on the rom used, the arcade core, and how things are laid out.

  • bits: bit number to fill out sent to the core in ioctl_data
  • name: title for the OSD
  • ids: title for each option in the OSD
  • values: if you want the values to be different than 0,1,2,3 you can reorder them
    <dip bits="16,17" name="Coinage" ids="2c/1cr,1c/1cr,1c/2cr,Free Play" values="3,1,2,0"/>

Addons overview

MiSTer FPGFA Addons

While the the MiSTer platform can be used with just the basic setup mentioned [here], its features can be greatly expanded with the use of additional expansions.

There are several options available and each has its own page. Here is a brief overview of each addon and a link to its page for further information.

How to get boards?

When you've gotten your DE10-Nano FPGA board, you will probably want to have the expansions like the SDRAM or IO board. There are two ways to do that:

1. Buy

Check the sale threads:

  • Add-On Sale Thread (Atari-Forum) NOTE: If you will find some sellers not mentioned in that thread, please post there the link and ask before purchase. There are some scammers who improperly solder the boards and sell even with higher price than you can get on the forum.
  • In general, it's best to prefer buyers that have been around for some time, and have some track record. Many are members of the forums and discord and you can find them easily there. It is also recommended to only buy official versions of the addons first, since MiSTer upgrades are not guaranteed to be compatible with unofficial hardware.

2. Do It Yourself

If you are a bit technically gifted or just want to learn how to assemble PCBs by yourself, then head over to the "Assembly (DIY)" guides in the wiki sidebar and make your own boards! You can discuss and share your experiences with us here:

SDRAM Board

Actual SDRAM Board Revisions: XS v2.2 and XSD v2.5

The MiSTer SDRAM Board, although optional, is considered an essential expansion board for the DE10-Nano FPGA board. The SDRAM is required by most cores of the MiSTer platform.

SDRAM Board Types

SDRAM Board Universal:

Advantages Disadvantages
Vertical Doesn't increase horizontal dimensions. Doesn't cover and allows better cooling for FPGA chip. Doesn't block Arduino GPIO - compatible with future or custom expansions. Easy to attach/detach. Slightly less maximum working frequency.
Horizontal Outward Doesn't cover and allows better cooling for FPGA chip. Doesn't block Arduino GPIO - compatible with future or custom expansions. Higher maximum working frequency. Increases horizontal dimensions.
Horizontal Inward Doesn't increase neither horizontal nor vertical dimensions. Higher maximum working frequency. Blocks Arduino GPIOs - incompatible with future or custom expansions (PCB v3.2 solves this issue). Covers FPGA chip and makes cooling harder. Temperature condition is quite bad. Not compatible with I/O board v4 and newer.

Install the SDRAM Board

The SDRAM Board will be inserted into the GPIO 0 Header of the DE10-Nano Board. Three additional pins will be inserted into the Arduino header JP3

When Plugging in the SDRAM Board, make sure to support the DE10-Nano from beneath with your thumbs. Forcing in the SDRAM Board without support can bend the DE10-Nano board and permanently damage it.

Removing the SDRAM Board can be tricky for some GPIO connectors and just pulling won't do it sometimes. For very tight connectors, it is recommended to wiggle the SDRAM Board back and forth to remove the connectors slowly, bit-by-bit. Just pulling with force will often bend the GPIO header.

Cores that use SDRAM

The table of the cores requiring SDRAM Board to function:

Name SDRAM Speed (MHz) Comments
Boot Menu 100 doesn't require the SDRAM board but uses if found. It erases the whole SDRAM(and DDR) memory while running
Amiga 57
Amstrad 64
Arcade Astrocade 57 only for samples in Seawolf II and Gorf (with speech)
Archie 126
Atari 800 57 only for memory config >320KB or Cartridge usage
Atari ST 96
BK0011M 96
ColecoVision 43
Commodore 64 64
Gameboy 66
GBA 100 Optional, Requires 33.5MB for 32MB games; will automatically use the onboard DDR3 RAM instead if SDRAM is not large enough
Genesis 107 Optional
MacPlus 65
Mega CD 107
MSX 85.9
NeoGeo 96 Requires up to 100MB of SDRAM depending on game
NES 85.9
QL 84
SAM Coupe 96
Sega Master System 96
SNES 85
TSConf 84
TurboGrafx16 86 Optional
X68000 80
ZX Spectrum 112

IO Board

Current Board Revision: 6.1 and digital IO 1.2

The MiSTer IO Board is an optional expansion. It adds the following features to the MiSTer Platform:

  • VGA Connector for Analog Video output. Capable of RGBs, YPbPr and standard VGA. Check Analog video output compatibility
  • 3.5mm Audio Jack with TOSLink
  • 3 Buttons
  • 3 Status LEDs
  • Secondary SD card (for some cores)
  • FAN for cooling the FPGA
  • Expansion connector (in the form of USB 3.0 connector, but it's not USB!)
  • Additional connectors to integrate the MiSTer into cases.

Secondary SD card

Introduction

Some cores require low-level SD card access. The primary SD card cannot provide low-level access due to an incompatible layout. It is also locked by Linux system from direct access. Thus, I/O board v5.x provides the secondary SD card which is directly connected to FPGA. Linux system doesn't see this card. The layout of the secondary SD card fully depends on core requirements. Usually, it's simple FAT16 format, but some cores may require custom formatting.

Schematics

Secondary SD card is a simple direct connection between SD connector and DE10-nano GPIOs. It's possible to solder by yourself if whole I/O Board is not required (or older I/O Board is used). Check the schematic if you want to connect it by yourself.

Cores with Secondary SD card support

Following cores support (but not require, see VHD section) the secondary SD card:

  • BBC Micro
  • MSX
  • Sinclair QL - SD support hasn't been confirmed yet - requires specific ROM. Current ROM doesn't use SD card.
  • TSConf

Following cores require the secondary SD card:

  • Sharp X68000

Use VHD files instead of secondary SD card

The cores where secondary SD card is optional require VHD image file to replace the SD card in order to work. VHD image is a simple dump of SD card. You can prepare a special SD card for specific core and then make a full backup using a utility such as Win32 Disk Imager. You even can create VHD file without SD card at all. In this case, you can create a smaller VHD file with suitable size in such application as WinImage - save it into IMA format and then rename to VHD.

Notes about VHD format

  • Usually FAT16 is required, but some cores can support FAT32 as well.
  • Content of VHD file should be exactly as it is originally required for Secondary SD card.
  • Most (but not all) cores support both non-MBR and MBR types of images. MSX core is known to support only MBR images. Tools like WinImage create only non-MBR images but may open and edit MBR images created somewhere else (like in disk dumper tool from a real prepared SD card).

How to use VHD files

You can make the image which will be mounted automatically at the start of the core. So, it will look like you have SD card connected at the start. For automatic mounting, you need to name the VHD as CoreID.VHD and place together with RBF file or create the folder CoreID and put BOOT.VHD image in that folder. The second option is convenient if you have several VHD files for the core, while the first option is more convenient if only a single file is used. CoreID is the name you see in core's OSD. For example, for Atari 800 core, the auto mounted name will be Atari800.vhd

How to use Secondary SD card and VHD

VHD file has priority over a real secondary SD card if mounted. Unmount the VHD (press BACKSPACE while choosing VHD file in OSD) in order to use the Secondary SD card.

Direct Video

Direct Video

Since autumn of 2019 there is a method for outputting analog video called Direct Video that doesn't require you to install the IO Board in your MiSTer. This new method offers same minimal latency to the VGA port from the IO Board and even better color depth in some cores. To enjoy it, you just need to activate the feature in your mister.ini file and attach a DAC to your HDMI port.

You may use a HDMI-VGA converter similar to this one

Compatibility

Direct Video is compatible with most current cores and will be supported in all future cores coming to MiSTer.

RGBs, RGsB and YPbPr are supported, although YPbPr has less display compatibility in Direct Video mode compared to YPbPr from the IO Board.

Note that output resolution and format can vary from core to core. See analog video output compatibility for more information.

How to Use

First you need a simple DAC with VGA output. Those based on the chip AG6200 (like the one in the picture) are proven to work fine and are fairly inexpensive and easy to find. Also many of them output analog audio too. The only thing we recommend is to not hotplug them or pull them out from your MiSTer while it is still ON, since you might damage your HDMI port in the process.

Then you need to add the following line to your mister.ini file:

direct_video=1

This activates the Direct Video feature when the system starts. Once it's enabled, it allows your HDMI port to output the raw and unprocessed digital audio/video signal from the loaded core, which is consumed by your DAC. MiSTer will not work with your HD TV or monitor while this mode is enabled, since they require a standard HDMI signal to work, and the zero-lag Direct Video signal IS NOT standard HDMI.

The resulting analog video signal from your DAC should be compatible with standard CRTs if the core loaded supports standard CRT refresh frequencies (see analog video compatibility for more details). But there is still a bit of additional configuration you need to do depending on which kind of analog video signal you want to use.

Setup for RGB signals

For analog RGB output, you'll want to enable composite sync on the HSync signal in your mister.ini (composite_sync=1). After that, you are good to plug in an RGB-compatible VGA-SCART cable to your TV.

For optimal results, Retro Access sells SCART and BNC cables specifically for use with MiSTer.

DISCLAIMER: Please be aware that many VGA DACs may output a sync signal at 3 volts or more on pin 13 (HSYNC/CSYNC) even when being used in Direct Video mode! You will need a 470 ohm resistor on the corresponding SCART sync pin to attenuate this signal to levels that are safe for all video equipment. A variety of professional video equipment can have wide tolerances for higher voltage sync signals but other devices, especially external scalers like the OSSC or XRGB Mini Framemeister, can be worn out and reduced to a non-working state by repeated use with higher-voltage sync signals. Unless you are 100% certain your equipment can tolerate higher voltage signals, it is strongly recommended that you either purchase a cable that has a 470 ohm resistor inline or add one yourself. Retro Access MiSTer SCART cables, for example, come with a resistor inline by default.

Setup for YPbPr signals

YPbPr - also known as Component Video - is available in Direct Video mode but has limited compatibility. This is due to limitations of HDMI-to-VGA DACs, which were not meant to produce signals in the YPbPr color space in the first place, resulting in signals that are slightly out-of-spec. It is possible that your display will accept the Direct Video YPbPr signal with no issue, but it may also appear bright pink due to the way many displays process such signals. For higher YPbPr compatibility you may prefer RGB mode with an external RGB-to-YPbPr transcoder instead, or YPbPr via the IO Board.

To use YPbPr in Direct Video mode, you'll need to enable composite_sync and ypbpr in your mister.ini file.

You'll also need to add a sync-on-green circuit on your VGA connection. Sync-on-green circuits can be very simple; you just need a diode (1N4148) and a 1k resistor. Connection: from HSync -> anode of diode, cathode of diode -> resistor, resistor to Green signal.

Doubling frequency

This is a handy way to use those modern monitors that have VGA input but are typically not compatible with 15KHz signals, and require 31KHz analog video. In case you need it, you just have to set forced_scandoubler=1 in your mister.ini to turn a 15KHz signal into a 31Khz one (See which cores output 15KHz video here).

Color Depth

Direct Video produces a 24bit color signal, which is superior to the 18bit signal coming from the IO Board. However, few cores use 24bit color, so the improved color depth may not make much of an impact depending on the cores you run.

Also, most cheap DACs, like the ones based on the chip AG6200, don't produce Full Range RGB. They instead produce Limited Range RGB (16-235) or much more commonly a nonspec Limited Range variant (16-255). In order to compensate for this, you may want to configure the hdmi_limited option in your mister.ini to adjust the signal being sent to your DAC.

  • Full Range (0-255): hdmi_limited=0.
  • Limited Range (16-235): hdmi_limited=1.
  • Limited Range common DAC variant (16-255): hdmi_limited=2.

Analog video output compatibility

Note

The VGA-style HD DB15 port on the IO board is intended for analog video output and does not explicitly output VGA or any one standard.

This page is titled to reflect this, as individual cores and configuration can vary. The default configuration is to output non-scaled video in an RGBHV mode. MiSTer can be configured to enable scaling, output RGBs, RGsB or component as well over this port. Native resolutions here denote video signals generated by the core by default and may not match original hardware. Display output frequencies and resolutions tend to change over a core's development. Some cores output multiple resolutions and formats, which may require a more general classification.

The primary display output of the DE10 nano is HDMI, so HDMI is often the initial target for video output in most cores.

Table of cores and resolutions supported over the RGB/VGA output

Consoles

CoreVersionNative ResolutionFrequency (Horizontal, Vertical)Notes
Atari260020181214240p15.40kHz, 59.4HzA startup rom must be placed in the core
Astrocade20181224240p15.70kHz, 59.9Hz
Atari520020180819240p15.62kHz, 59.9hz
Colecovision20181130240p15.49kHz, 59.7Hz
Gameboy20200331240p15.77kHz, 59.7HzEnable "Stabilize video" to prevent sync issues on blank screens
GBA20200409240p15.77kHz, 59.7Hz
Genesis20200502240p15.72kHz, 59.9Hz
NeoGeo20200325240p15.63kHz, 59.2Hz
NES20200308240p15.75kHz, 60.1Hz
Odyssey220181221240p15.61kHz, 60.1Hz
SMS20200309240p15.7kHz, 59.9Hz
SNES20200306240p15.75kHz, 60.1Hz
TurboGrafx16 (PC Engine)20181231240p15.56kHz, 59.7Hz
Vectrex20180616VGA44.96kHz, 60.0Hz

Computers

CoreVersionNative ResolutionFrequency (Horizontal, Vertical)Notes
Acorn Archimedes20180519240p16.22kHz, 52.2Hz
Altair 880020181113VGA45.03kHz, 60.0Hz
Amiga20181216240p15.68kHz, 50.4Hz
Amstrad CPC 61282018084240p15.63kHz, 50.25Hzboot rom needed
48620181215VGA44.95kHz, 60.0Hz
Apogee20180305240p15.44kHz, 50.0Hz
Apple II+20180308VGA30.62kHz, 58.5Hz
Apple Macintosh Plus20180305Mac22.06kHz, 60.1Hz
Aquarius20180429240p15.49kHz, 59.6Hz
Atari 80020180812240p15.63kHz, 59.9Hz
Atari ST1VGA31.13kHz, 49.9Hz
BBC Micro20180521?62.5kHz, 62.5kHz
BK0011M20180901240p15.82kHz, 48.82Hz
Commodore 6420180831240p15.31kHz, 58.4Hz
Commodore 1620180902240p15.50kHz, 49.8Hz
Commodore PET20180305240p15.49kHz, 59.6Hz
Commodore VIC-2020180926240p15.54kHz, 59.8Hz
PDP-1201901011280x102463.80kHz, 59.9Hz
MSX20180520240p15.62kHz, 59.9Hz
MultiComp20180629VGA30.99kHz, 59.6Hz
Sharp MZ Series20180927240p15.01kHz, 58.0Hzno HDMI output
Sinclair QL20180305240p15.74kHz, 60.3Hz
Specialist/MX20180305yes15.61kHz.50.0Hz
Tandy CoCo3091918aVGA31.28kHz, 59.9Hz
TI-99/4A20180527240p15.38kHz, 59.88HzA startup rom must be placed in the core
TSConf20180901240p15.51kHz, 50.0Hz
Vector 06C20180304240p15.51kHz, 50.0Hz
X6800020171103NANA
ZX Spectrum20181231240p15.51kHz, 48.8Hz
ZX8120180903240p15.62kHz, 59.9Hz

Arcade

CoreVersionNative ResolutionFrequency (Horizontal, Vertical)Notes
194220180313VGA37.77kHz, 60.3HzTATE, image squished over HDMI
Alibaba20180313240p15.49kHz, 59.1Hz
Amidar20180313240p15.86kHz, 60.6Hz
AzurianAttack20180313240p15.86kHz, 60.6Hz
Bagman20180313240p15.86kHz, 60.6Hz
BlackHole20180313240p15.86kHz, 60.6Hz
BombJack20180313240p15.49kHz, 59.1Hz
Bubbles20181217240p15.49kHz, 59.1Hz
BurgerTime20180313240p15.49kHz, 59.1Hz
BurningRubber20180313240p15.49kHz, 59.1Hz
Catacomb20180313240p15.49kHz, 59.1Hz
Colony720181218240p15.49kHz, 59.1Hz
ComputerSpace20180313240p15.49kHz, 59.1Hzmenu not available over VGA
CosmicAvenger20180313240p15.89kHz, 61.1Hz
CrazyClimber20180607240p15.49kHz, 59.1Hz
CrazyKong20180313240p15.49kHz, 59.1Hz
CrushRoller20180313240p15.49kHz, 59.1Hz
Defender20180313240p15.49kHz, 59.1Hz
DonkeyKong20180418240p15.86kHz, 60.6Hz
Dorodon20180313240p15.86kHz, 60.6Hz
DreamShopper20180313240p15.86kHz, 60.6Hz
Eeekk20180313240p15.86kHz, 60.6Hz
Eyes20180313240p15.86kHz, 60.6Hz
Frogger20180313240p15.86kHz, 60.6Hz
Galaga20180313240p15.86kHz, 60.6Hz
Galaxian20180313240p15.86kHz, 60.6Hz
GalaxyWars20171115VGA37.8kHz, 60.3Hz
Gorkans20180313240p15.86kHz, 60.6Hz
Invaders20181010VGA31.20kHz, 59.9Hz
Joust20181216240p15.49kHz, 60.0Hz
LadyBug20180313240p15.49kHz, 60.0Hz
LizardWizard20180313240p15.49kHz, 60.0Hz
LodeRunner20171115VGA37.8kHz, 60.3Hz
LunarRescue20171115VGA37.8kHz, 60.3Hz
Mayday20181218240p15.49kHz, 60.0Hz
MoonCresta20180313240p15.49kHz, 60.0Hz
MoonPatrol20180315240p15.51kHz, 50.0Hz
MrDoNightmare20180313240p15.49kHz, 59.1Hz
MrTNT20180313240p15.49kHz, 59.1Hz
MsPacman20180313240p15.49kHz, 59.1Hz
Omega20180313240p15.49kHz, 59.1Hz
Orbitron20180313240p15.49kHz, 59.1Hz
Pacman20180313240p15.49kHz, 59.1Hz
PacmanClub20180313240p15.49kHz, 59.1Hz
PacmanPlus20180313240p15.49kHz, 59.1Hz
PacmanicMiner20180313240p15.49kHz, 59.1Hz
Pengo20180313240p15.49kHz, 59.1Hz
Phoenix20180313240p15.49kHz, 59.1Hz
Pisces20180313240p15.49kHz, 59.1Hz
Ponpoko20180313240p15.49kHz, 59.1Hz
Pooyan20180313240p15.49kHz, 59.1Hz
Robotron20181215240p15.49kHz, 59.1Hz
Scramble20180929240p15.86kHz, 60.6Hz
Sinistar20181218240p15.86kHz, 60.6Hz
SnapJack20180315240p15.86kHz, 60.6Hz
Space Attack II20171115VGA37.8kHz, 60.3Hz
Space Invaders20171115VGA37.8kHz, 60.3Hz
Space Invaders Part II20171115VGA37.8kHz, 60.3Hz
Space Laser20171115VGA37.8kHz, 60.3Hz
Splat20181217240p15.86kHz, 60.6Hz
Stargate20181216240p15.86kHz, 60.6Hz
Super Earth Invasion20171115VGA37.8kHz, 60.3Hz
SuperGlob20180313240p15.86kHz, 60.6Hz
TheEnd20180313240p15.86kHz, 60.6Hz
TimePilot20180313240p15.86kHz, 60.6Hz
VanVanCar20180313240p15.86kHz, 60.6Hz
WarOfTheBugs20180103240p15.86kHz, 60.6Hz
Woodpecker20180313240p15.86kHz, 60.6Hz
Xevious20180313240p15.86kHz, 60.6Hz
ZigZag20181219240p15.86kHz, 60.6Hz

TO-DO:
Declare specific resolution
Specify if PAL/NTSC alternate is available
Note is core expecting horizontal or vertical orientation

RTC board

Some cores (ao486, Minimig) use clock, so MiSTer provides the real time for such cores. MiSTer can take the time from internet if active connection is present.

This board is pretty simple and provide real time offline. It supports 2 types of battery holders and several types of RTC ICs. It's plugged into LTC connector.

Assembling notes

  • If through hole battery holder is used, you need to cut all its plastic pins and make sure the holder is fully seated on board without gaps. Otherwise it may touch the I/O board and make short circuit.
  • For through hole holder, make sure you cut the pins as short as possible so it won't protrude under the board which can make short circuit.
  • The board has the hole on opposite side of connector. Use a plastic(or other non-conductive) screw to make a leg and prevent the board bend and touch the main board.
  • SMD holder (left picture) is preferable as it's more slim.

Usage notes

To get real time saved, simply connect MiSTer to internet and let it run for around 15 minutes. or from the console:

By default the time zone is UTC(GMT). If you want to get the time of your zone, you need to do following:

  • connect to MiSTer by FTP/SFTP
  • navigate to /usr/share/zoneinfo/posix folder and find there the name of your place or time zone.
  • copy that file to your computer under name timezone
  • copy it back to MiSTer to folder /media/fat/linux with name timezone

From the console you can also force the hardware clock to update and read the time from it.

  • store datetime to RTC : hwclock -wu
  • read RTC : hwclock -u

Core support

RTC is supported in following cores:

  • ao486
  • Archie
  • BBC Micro Master 128K
  • Minimig
  • MSX
  • TSConf

If you have internet connection or RTC board installed, these cores will show correct time and date.

USB Hub

This is an optional add-on usb hub pcb made for convenient USB device connections. With this board the MiSTer has an extra seven USB ports that fit snugly under the existing chassis.

Order v1.2 PCB on PCBWay

Order USB Bridge board PCB on PCBWay

The Hub is based on the FE2.1 chip, which requires only a few external components. It uses 3 sides for USB sockets. Since the input Micro-USB connector has a flexible wired connection to the board, the user can mount it in either direction to choose the side providing the USB connections.

The Hub add-on board allows you to use power from Micro-USB or external power. External power is preferred as this will prevent USB over-current triggering. In case external power is used, a small cut point (shown on picture) should be cut (or you can leave the Micro-USB +5V wire unsoldered)!

3D-printed (DIY)

A custom case for your MiSTer can be 3D printed using these files from Thingiverse. There are separate models which you can use depending on the add-ons that you have.


Universal Case for the MiSTer to now support the I/O-Board 5.2 and all SDRAM configurations

MiSTer Sidecar USB case add-on usable with MiSTer USB Hub v1.1 daughter board Sidecar will with MiSTer - Case Universal v5.2 and v1.2


MiSTer XS Case v1 - v5.2 XS for SDRAM XS - extra slim - v1.1

MiSTer XS Case v2 - v5.2 XS for SDRAM XS - extra slim - v1.1 (the case is 4 mm higher than v1)

Case with fan holder which fits vertical and horizontal SDRAM boards (Case Universal)

Slimmed down case that only fits vertical SDRAM board

MiSTer - Case v1.0 Updated

Original case that only fits horizontal SDRAM board

MiSTer board

3D model (STEP 3D) for case development: MiSTer with I/O Board v5.2 and SDRAM XS v1.1

Pi-Top (v1)

This is an attempt to put MiSTer into Pi-Top v1 (original) case and make a MiSTer notebook.

Main note:

v1 case is discontinued by manufacturer. It just disappeared from the site. This case is still available from distributors such as RS-Online, Sparkfun, but won't last long. So, hurry up if you want to put MiSTer into this case! You may buy it even if you are not sure. You still can use this case for RPi/TB in case if you will change your mind.

This is not a budget case.

Case is pretty expensive but the only solution on the market. High price of the case doesn't mean good quality, alas. Plastic used on the case is so-so. Connections between plastic details aren't good either. Be careful as some parts are easy to brake (although pi-top site is full of pictures with children). Overall it looks like cheap case, but as has been said, there is no other option on the market to make your own notebook.

You can think about adaptation of some (old) notebook case. But it will be more hard and possibly even more expensive. Notebook displays usually have either LVDS or eDP interface while Pi-Top has HDMI. So you will need to find/make a conversion board for notebook display which is not always possible. Keyboard and touchpad in traditional notebook have "naked" interfaces providing low-level connection while Pi-Top provides USB connection for both keyboard and touchpad. So you will need to make another conversion board for keyboard and touchpad on traditional notebook. Battery management on traditional notebook is on main board, so another board is required while Pi-Top provides integrated HUB board to manage the battery and display power control. So, adaptation of traditional notebook will require pretty large board to convert internal interfaces to those compatible with MiSTer(DE10-nano). Different notebooks have different internals, so it's impossible to make a one board for all notebook cases. And usually even in old thick notebooks there is no much space to fit DE10-nano - especially in height dimension.

So, after judge all these difficulties, the only viable option is Pi-Top case.

There are 2 versions of Pi-Top cases.

This project is targeted to v1 (called as original on Pi-Top site) case only. This version has more space inside and has no specific to RPi holes and places. So, we have pretty relaxed placement of DE10-nano inside. Semi-transparent cover gives good view to all DE10-nano LEDs and doesn't require to drill the holes. v1 uses railed holes to fix the boards, while v2 case uses magnet rails not suitable for this project.

Probably it's possible to use v2 case as well, but it will require completely different add-on boards.

v2 is available only in childish acid green color which is a main distraction point.

You need to be very careful while messing with internals.

  • There is high voltage on HUB board and its connector. It's highly advised to de-solder and remove pin 1 from PiTopHUB connector. It delivers 16.5V and very dangerous for DE10-nano. There is no usage of 16.5V so it's better to remove this pin. Connector on PiTopHUB isn't shrouded and it's very easy to shift it while connecting and fry everything!
  • Many parts on PiTopHUB are powered even when main power of Pi-Top is turned off. It's result of bad Pi-Top design. So, you need to be careful. Don't drop any metallic parts on the board. Avoid to touch the board.

Buggy MCU firmware.

While developing the boards for Pi-Top i found it's easy to make MCU on PiTopHUB to stick in non-responsible state. And since MCU is always powered (even in power off state) power cycle isn't enough. There are 2 ways to reset the MCU.

  1. Remove PiTopHUB and effectively remove the power from MCU.
  2. Carefully short the two lower pins on tiny 6-pin connector - this is reset of MCU.

New releases required.

New releases of Linux, MiSTer binary and Cores are required. Releases after March 02 2018 will be compatible with Pi-Top. Display of Pi-Top supports only one resolution - 1920x1080. So every core will require to support this resolution.

Butter-smooth video

Although Pi-Top display supports only single resolution, it accepts any (reasonable) pixel clock and refresh rate. So, with this display and automatic VSync adjust option video may have original retro system refresh rate. All scrollers will be very smooth.

Required Boards

Gerber and PDF files for all boards can be found here

Main Board (Order on PCBWay)

This board has all important parts such as memory, both SD cards and Audio.

Memory

Both SDRAM (32MB) and SRAM (2MB) are on this board, although SRAM is not supported by any core. There are no plans to use SRAM in foreseen future, so it's advised not to solder SRAM and save the cost.

SD Cards

Board has the same secondary SD card as on original MiSTer board. Another SD card is original DE10-nano card through micro-SD extender providing convenient access to card as original is in hard to reach place.

Audio

Audio amplifiers may be soldered directly on board by components, or using Adafruit audio breakout boards by soldering connectors points. MAX98357A has very tiny pads - if you are not sure in your soldering capability, use the breakout boards. The price is about the same as set of components. Although board has places for audio amplifier, it's advised not to solder it. Audio amplifiers gives up to 3.2W per channel and may draw up to 1.2A from 5V source. Due to audio nature, the draw will not be constant and will hammer the DE10-nano power circuit. So, it's advised to solder audio amplifiers on separate Audio board. By default 5V power of audio is connected to 5V of DE10-nano. There is an option to use external 5V supply for audio by cutting tiny cut point near P6 connector and connect external 5V (take from Audio board) source to unload internal DE10-nano power circuit.

Notes

Due to height limit in Pi-Top case, this board is mounted at some angle. P1 uses standard profile connector while P2 uses high profile connector (same as on standard MiSTer I/O Board). Thus one side of Arduino connector will slightly protrude from this board's cutout while other side will be covered by the board. You need to cut pins on both connectors at the board level before soldering to make sure it won't prevent closing of sliding cover. (pictures are coming) P4(primary card extender) and I2S_FPGA (if you use audio board) are better to be soldered as SMD using exposed pads on the bottom of the board for the same reason.(pictures are coming)

Recommended board thickness is 1.2mm. This board thickness is included to total height of the whole construction.

Audio Board (Order on PCBWay)

Using sockets for speakers: Directly wired:

Audio amplifiers can be soldered directly on board by components, or using Adafruit audio breakout boards by soldering connectors points. MAX98357A has very tiny pads - if you are not sure in your soldering capability, use the breakout boards. The price is about the same as set of components.

Set on-board DE10-nano switches according to picture to enable I2S output to audio board:

Besides audio amplifiers, the boards are providing I2C and SPI connections to DE10-nano (through RTC board). I2C is used for battery monitoring. SPI is used for display brightness control. It's also providing power for fan. Fan power circuit has flexible way to adjust the power using diodes and resistors (see schematics).

Recommended board thickness is 1.0mm. This board thickness is included to total height of the whole construction.

RTC Board (Order on PCBWay)

RTC v1.3(or higher) is required to provide I2C and SPI connections. You don't need to populate the board if RTC is not required. You may connect I2C/SPI directly to DE10-nano without RTC board using 14-pin cable connector - just follow the RTC schematics.

It's better to trim connector pins on the bottom of DE10-nano board to prevent the cable puncture:

Recommended board thickness is 1.6mm

USB HUB Board (Order v2 on PCBWay) (Order v3 on PCBWay)

You may solder dual USB2-3 socket directly to the board, or (as shown on pictures) solder single socket with other socked hanging on wires to fit some larger USB device (such as 8BitDo receiver) inside. This board provides convenient USB device connections - both internal(3xUSB) and external(1xUSB). Board also provides mini-USB pass-through for console (or USB Blaster if required). This is optional board. You may use any tiny USB HUB to connect devices as you like.

There are 2 versions:

  • v2 - based on 2 FE1.1S chips. This version is enough for most users. SSOP28 chips are relatively easy to align and solder.
  • v3 - based on FE1.1 (periphery hub) and FE1.1S (Console+Blaster). FE1.1 is MTT USB hub providing high performance for mixed usage when both slow devices like keyboard/gamepad and high performance devices like WiFi or USB storage connected at the same time. FE1.1 uses LQFP48 package which is harder to align and solder.

Both versions have 2 Hubs on board. If you are not actively developing FPGA cores, then most likely you don't need to solder the hub on U2 chip. Only solder the hub based on U1 chip and then mUSB1 and the miniUSB "tail" to P2.

Recommended board thickness is 1.0mm. This board thickness is included to total height of the whole construction.

LEDs

Pi-Top v1 case has large semi-transparent door, so any lights will be visible through. Thus LEDs on DE10-nano are used for indications. Main Board provides the power LED.

Buttons

Use keyboard to simulate OSD(F12), User(LCtrl-LAlt-RAlt) and Reset(LShift-LCtrl-LAlt-RAlt) buttons.

It's possible to use hardware reset button by short press of power button but it requires hardware modifications of DE10-nano.

Power button.

Pi-Top power button requires about 2 seconds hold to turn the power on/off. If brightness has been changed since power on, then power button requires around 3-4 seconds hold to turn the power off.

Cooling

Cooling is necessary as the space around the main chip is to small for passive cooling! The construction uses the turbine fan. It takes air from bottom of the case (remove one magnetic plate on the bottom for air flow) and blows to the side under AIO board all the way to hole on the right of PiTop case. It's hard to screw the fan. There are many different fans on the market. Currently used fan just lays unattached - surrounded parts just keep the fan in place.

More pictures

You need to buy USB-to-barrel short cable to connect the power to DE10-nano board.

Optionally AIO board can be covered by black tape for additional protection.

AIO board detached:

Unused ADC header has been removed from DE10-nano to improve LEDs view. Black tape attached to Ethernet connector is to reduce glow effect.

Bonus: v2 consideration

This is how bare DE10-nano fits inside v2 case: Cover cannot be closed. Board doesn't fit. Picture shows the maximum closed position of the cover. Probably, after removing the metallic rail road and cutting the plastic ribs, DE10-nano will be able to fit. So, irreversible modification of the case will be required with drilling the holes. Most likely it's possible to use the same AIO and Audio boards. It will require other USB hub board to accommodate RPi holes on the back of the case.

Height comparison v1 vs v2: Basically, v2 is a little slimmer on the back and a little thicker on the front. But without side-by-side comparison it's hard to notice the differences.

Overall comparison of v2 to v1:

  • (-) Only green color available.
  • (+) Slightly better tactile feeling of the case. It's not so slippery as v1.
  • (+) Wider keyboard and bigger touchpad.
  • (-) Cannot fit DE10-nano without butchering the case.
  • (-) Non transparent cover. Cannot see any indication from the board.
  • (-) Almost no holes (v1 has big holes around hinges), everything is tightly coupled -> needs to drill the holes for speakers.

Conclusion: use v2 for Raspberry Pi or Asus Tinker Board ;)

Arcade cores

MRA format description


Core porting notes

Introduction

MiSTer uses quite complex hardware, but thanks to open source, developers with different levels of hardware/software knowledge can develop for this platform. Many cores for MiSTer use common almost identical part of code simplifying access to hardware and firmware called Framework. We will use ZX Spectrum core in this guide.

Framework

Most of the sources of the Framework are located in sys folder. Usually, for a new project, you need to take following files/folders

  • sys folder
  • jtag.cdf
  • jtag_lite.cdf
  • zxspectrum.qpf (project file. Keep it read-only to prevent it from automatic changes whenever you switch between fill and lite versions and spam your change history)
  • zxspectrum.qsf
  • zxspectrum.srf (some warnings ignores)
  • zxspectrum-lite.qsf
  • zxspectrum-lite.srf (some warnings ignores)

You need to make some changes:

  • Rename zxspectrum.* files according to a new project.
  • Inside files find the "zxspectrum" word and replace it with the name of your project.
  • in *.qsf files at the end you will find the list of project files. Remove files not related to your project.

The initial set of files for the new project is ready. Now you can open the project in Quartus 17.0 or higher. Assuming you are porting some existing core to MiSTer, the top module entity should be renamed to emu. See zxspectrum.sv and its input/output signals:

module emu
(
    //Master input clock
    input         CLK_50M,

    //Async reset from top-level module.
    //Can be used as initial reset.
    input         RESET,

    //Must be passed to hps_io module
    inout  [37:0] HPS_BUS,

    //Base video clock. Usually equals to CLK_SYS.
    output        CLK_VIDEO,

    //Multiple resolutions are supported using different CE_PIXEL rates.
    //Must be based on CLK_VIDEO
    output        CE_PIXEL,

    //Video aspect ratio for HDMI. Most retro systems have ratio 4:3.
    output  [7:0] VIDEO_ARX,
    output  [7:0] VIDEO_ARY,

    output  [7:0] VGA_R,
    output  [7:0] VGA_G,
    output  [7:0] VGA_B,
    output        VGA_HS,
    output        VGA_VS,
    output        VGA_DE,    // = ~(VBlank | HBlank)

    output        LED_USER,  // 1 - ON, 0 - OFF.

    // b[1]: 0 - LED status is system status ORed with b[0]
    //       1 - LED status is controled solely by b[0]
    // hint: supply 2'b00 to let the system control the LED.
    output  [1:0] LED_POWER,
    output  [1:0] LED_DISK,

    output [15:0] AUDIO_L,
    output [15:0] AUDIO_R,
    output        AUDIO_S, // 1 - signed audio samples, 0 - unsigned
    input         TAPE_IN,

    //High latency DDR3 RAM interface
    //Use for non-critical time purposes
    output        DDRAM_CLK,
    input         DDRAM_BUSY,
    output  [7:0] DDRAM_BURSTCNT,
    output [28:0] DDRAM_ADDR,
    input  [63:0] DDRAM_DOUT,
    input         DDRAM_DOUT_READY,
    output        DDRAM_RD,
    output [63:0] DDRAM_DIN,
    output  [7:0] DDRAM_BE,
    output        DDRAM_WE,

    //SDRAM interface with lower latency
    output        SDRAM_CLK,
    output        SDRAM_CKE,
    output [12:0] SDRAM_A,
    output  [1:0] SDRAM_BA,
    inout  [15:0] SDRAM_DQ,
    output        SDRAM_DQML,
    output        SDRAM_DQMH,
    output        SDRAM_nCS,
    output        SDRAM_nCAS,
    output        SDRAM_nRAS,
    output        SDRAM_nWE
);

These signals are main connections to MiSTer. You need to modify your core according to these signals.

API

Most top-level signals should be self-descriptive and more or less familiar to core developers, so I won't go too deep into it. I will describe some important parts where you need to pay attention to make your core work.

input   RESET

This signal is asserted while ARM part is under initial preparation. It can be used as an initial reset. It won't be asserted anymore during the whole work of core except when the user chooses another core from OSD. Then ARM will assert RESET in the existing core to let it stop any possible activity before switching to another core (cores loaded through USB Blaster won't get "bye-bye" RESET). If core uses DDR3 memory (Scaler isn't counted) then initial and bye-bye RESET is crucial for correct work. You will get a hard hang if DDR3 is accessed during RESET.

inout  [37:0] HPS_BUS

Pass it as-is to hps_io module.

output        CLK_VIDEO,
output        CE_PIXEL,
output  [7:0] VIDEO_ARX,
output  [7:0] VIDEO_ARY,
output        VGA_DE,

Besides other well-known VGA_* signals, these signals are important in MiSTer in order to get a proper display. CLK_VIDEO and CE_PIXEL are used to sample the pixels. If pixel rate equals to CLK_VIDEO, then set CE_PIXEL=1. Many cores have common system clock where pixel frequency is the product of the division of system clock to some number. In this case, set CLK)VIDEO to the system clock and assert CE_PIXEL at clock cycles where a new pixel is produced. Look in zxspectrum.sv to see how it's done. without CLK_VIDEO, you can still have VGA output, but OSD won't work.

VIDEO_ARX and VIDEO_ARY define aspect ratio on HDMI output. It doesn't affect VGA output. Usually VIDEO_ARX=4, VIDEO_ARY=3 or VIDEO_ARX=16, VIDEO_ARY=9. They can have other values but with extreme values, you may have video problems.

VGA_DE is another crucial part for MiSTer. Basically, it's opposite to blank signals: ~(VBlank | HBlank) but with some notes. HDMI video scaler detects the horizontal resolution by first active video line. So, you need to be sure the first line is not cut due to unaligned VBlank and HBlank signals to each other. Otherwise, you will get a messed HDMI video.

VGA_HS and VGA_VS should have positive pulse polarity.

output        AUDIO_S

Make sure you set correct mode signed/unsigned, otherwise audio will be distorted.

DDRAM_ are signals of DDR3 memory. If the core can use this memory instead of SDRAM, then it won't require SDRAM board.

SDRAM_ are signals of SDR SDRAM memory. The core will require SDRAM board if it uses these signals.

HPS_IO

There is a supplementary module hps_io.v which is also required to use in the same entity (see zxspectrum.sv). It provides in/out control from ARM side. Most signals are same or similar to MiST (user_io+data_io or mist_io modules) signals. So, if the core is ported from MiST, it in most cases it's 1:1 signal connections.

MiSTer has some changes/improvements over original MiST io modules:

  • Supports up to 4 images mount at the same time (MiST has only 1). Set module parameter VDNUM to 2..4 if more than 1 mounted image is required. If VDNUM=1 then related signals are same as in MiST.
  • Due to SD card on MiSTer uses multiple partitions and holds other vital to MiSTer parts, access to whole SD card from cores is not available in MiSTer. Only the access to image files is possible. Cores requiring direct access to whole SD card should be redesigned to access to images only.
  • Main MiSTer file system on SD card is exFAT which supports files bigger than 4GB.
  • OSD supports up to 15 lines (7 lines in MiST) which is handy for many cores.
  • ARM<->FPGA communication is done through the parallel bus which speeds up the communication. It supports 16bit I/O.

There are some other under the hood improvements in firmware like Keyboard/Mouse/Joystick setup.

Core configuration string

MiSTer provides an on-screen display (OSD) that can be toggled on and off by pressing F12 on your keyboard (or OSD button). For each core that is loaded, this menu can be configured to add specific options for that core.

The top-level module for the cores is emu. This does NOT mean emu is the top-level module for the project, but rather it is the top-level module for our purposes. The emu module is typically found in the SystemVerilog file (\.sv extension) with the same name as the project. As an example, the Arcade-Galaga project has it's top-level module at Arcade-Galaga.sv*.

The configuration string is stored in the variable CONF_STR of the emu module. This variable is passed to the hps_io module that handles sending it to the processor to be read when necessary.

Each line of the configuration string is delimited with a semicolon. The first line is the core name followed by 2 semicolons.

Valid options for the menu ([] - means optional parameter):

  • T{Index},{Name} - Trigger button. This is a simple button that will pulse HIGH of specified {index} bit in status register. A perfect example of this is for a reset button. {Name} is the text that describes the button function.
  • O{Index1}[{Index2}],{Name},{Options...} - Option button that allows you to select between various choices. {Index1} and {Index2} are values from 0-9 and A-V (like Hex but it extends from A-V instead of A-F). This represents all 31 bits. First and second index are the range of bits that will be set in the status register. {Name} is what is shown to describe the option. {Options...} is a list of comma separated options.
  • - Skips line.
  • F,{Ext}[,{Text}] - Load file button. {Ext} is a string of 3 character extensions. For example, BINGEN would be BIN and GEN extensions. Optional {Text} string is the text that is displayed before the extensions like "Load RAM". If {Text} is not specified, then default is Load *.
  • R{Index},{Name} - Same as T option but closes the OSD after selecting. Convenient for Reset option.
  • S{Slot},{Ext}[,{Text}] - Mount SD card button. {Slot} is a value from 0-3. Up to four images can be mounted at the same time. {Ext} - same as in F option. Optional {Text} string is the text that is displayed before the extensions like "Load RAM". If {Text} is not specified, then default is Mount *.

Non-OSD options (must be placed at bottom of configuration string):

  • J[1],{Button1}[,{Button2},...] - J1 means lock keyboard to joystick emulation mode. Useful for keyboard-less systems such as consoles. {Button1},{Button2},... is list of joystick buttons used in the core. Up to 12 buttons can be listed. Analog axis are not defined here. The user just needs to map them through the Menu core. As for the developer, just plug your module to them.
  • V,{Version String} - Version string. {Version String} is the version string. Takes the core name and appends version string for name to display.

Compiling for ARM

Cross Compiling for ARM

The ARM core on the DE-10 Nano is an ARM Cortex-A9 dual core You can grab a cross compiler for compiling ARM binaries on a 64bit intel based desktop system - eg OSX, Linux, or Windows (in the Linux subsystem)

Using a cross compiler on a Linux system

wget -c https://releases.linaro.org/components/toolchain/binaries/6.5-2018.12/arm-linux-gnueabihf/gcc-linaro-6.5.0-2018.12-x86_64_arm-linux-gnueabihf.tar.xz

Unpack somewhere useful, eg /opt

tar xf gcc-linaro-6.5.0-2018.12-x86_64_arm-linux-gnueabihf.tar.xz

and add to your path.

export CC='/opt/gcc-linaro-6.5.0-2018.12-x86_64_arm-linux-gnueabihf/bin/arm-linux-gnueabihf-gcc'

then follow up with the usual make..

Using Docker

Docker has a arm7 cross compiler which is easy to install on Mac or Linux (assuming you have docker installed already!)

docker run --rm dockcross/linux-armv7 > /usr/local/sbin/dockcross-linux-armv7

chmod +x /usr/local/bin/dockcross-linux-arm7

You can then cross-compile with

/usr/local/bin/dockcross-linux-arm7 make ./MakeFile

or (to compile a fictitious hello.c -> hello.arm)

/usr/local/bin/dockcross-linux-arm7 bash -c '$CC hello.c -o hello.arm'

Using msys on Windows 10

After installing msys, download the latest linaro binary release e.g. gcc-linaro-7.4.1-2019.02-i686-mingw32_arm-linux-gnueabihf.tar.xz From this location: https://releases.linaro.org/components/toolchain/binaries/latest-7/arm-linux-gnueabihf/

Extract it into your /opt/ folder under msys (e.g. C:\msys64\opt\) as "linaro", then when running MSYS set your PATH variable to point to it: export PATH=$PATH:/opt/linaro/bin

Alternatives

Another, more complicated option for big projects targeting for ARM

Compiling the u-boot boot loader for MiSTer

There are few reasons why you would want to modify, build, and install the u-boot boot loader used by MiSTer. It is assumed anyone undertaking this is aware of the risks and prepared to deal with them.

Disclaimer: Although unlikely, misconfiguring the boot loader could lead to hardware damage.

Realistically, in the worst case, you will have to use a computer to reinstall the original u-boot image on the appropriate partition of your SD card.

Why would you want to build a custom u-boot? The most common scenario is that there is some hardware peripheral or feature of the Altera Cyclone V SoC FPGA that you seek to enable, possibly for experimentation or adding a custom hardware capability to your MiSTer. In short, the ''why'' is left to the reader, and the ''how'' is addressed below.

High-level steps for building a MiSTer-compatible u-boot

Building a working u-boot image seems to requires an ARM cross-compilation toolchain with GCC version 4 or 5 (earlier may work but was not tested). Warning: In my experience, using a later version of GCC produces a u-boot image that is unable to reboot without a power cycle.

  1. Set up a cross-compilation environment as documented in the instructions for Compiling the Linux Kernel for MiSTer, but do not download or install the ARM toolchain.

  2. I suggest downloading and installing the Linaro 5.5-2017.10 toolchain, as it is the latest version that I found works properly. The current stock u-boot image distributed with MiSTer was compiled with GCC 4.8, so Linaro 4.9-2017.01 is another reasonable choice and still available for download as a binary at the time of this writing.

    wget -c https://releases.linaro.org/components/toolchain/binaries/5.5-2017.10/arm-linux-gnueabihf/gcc-linaro-5.5.0-2017.10-x86_64_arm-linux-gnueabihf.tar.xz
  3. Continue with the steps for installing the toolchain detailed in Compiling the Linux Kernel for MiSTer, substituting "5.5-2017.10" for the Linaro version.

  4. The u-boot source is available in the https://github.com/MiSTer-devel/u-boot_MiSTer repository (--depth=1 clones only the recent version, slimming down the download; omit this if you would like the full commit history):

    git clone --depth=1 https://github.com/MiSTer-devel/u-boot_MiSTer
  5. Compile the source:

    cd u-boot_MiSTer
    make MiSTer_defconfig
    make -j6
  6. Copy the u-boot image over to your MiSTer device. Note that the file must be copied to linux/uboot.img on your SD card. I suggest making a backup copy of the original linux/uboot.img. For example, if you are using scp:

    scp root@[IP address of your MiSTer]:/media/fat/linux/uboot.img uboot.img.orig
    scp u-boot-with-spl.sfp root@[IP address of your MiSTer]:/media/fat/linux/uboot.img
  7. Install the u-boot image on the appropriate partition of your SD card:

    ssh root@[IP address of your MiSTer]
    cd /media/fat/linux
    ./updateboot
  8. Power cycle your MiSTer (as opposed to a warm reboot).